diff --git a/admin/rfc.sh b/admin/rfc.sh index a37426b9b..06f050613 100755 --- a/admin/rfc.sh +++ b/admin/rfc.sh @@ -358,7 +358,7 @@ create) -f "./doc/devel/rfc_dropped/${name}.txt" ]]; then echo "$name.txt exists already" else - source ./doc/devel/template_rfc.sh >"./doc/devel/rfc_pending/${name}.txt" + source ./doc/devel/template/new_rfc.sh >"./doc/devel/rfc_pending/${name}.txt" edit "./doc/devel/rfc_pending/${name}.txt" 2 abstract git add "./doc/devel/rfc_pending/${name}.txt" process "./doc/devel/rfc_pending/${name}.txt" diff --git a/doc/devel/rfc_pending/VersionNumberScheme.txt b/doc/devel/rfc_pending/VersionNumberScheme.txt new file mode 100644 index 000000000..1894ab1e0 --- /dev/null +++ b/doc/devel/rfc_pending/VersionNumberScheme.txt @@ -0,0 +1,160 @@ +VersionNumberScheme +=================== + +// please don't remove the //word: comments + +[grid="all"] +`------------`----------------------- +*State* _Idea_ +*Date* _Mi 09 Mär 2011 02:00:41 CET_ +*Proposed by* Ichthyostega +------------------------------------- + +[abstract] +******************************************************************************** +Define and use a version numbering scheme for all releases, including the +development releases. Use the rules of the debian policy as a guideline. +******************************************************************************** + +Description +----------- +//description: add a detailed description: + +It should be clear right from start how version numbers are to be generated. +This numbering scheme should include a pattern for development builds. The +Debian policy defines a nice algorithm for ordering extended version numbers, +which could be used as a guideline. The sequence of version numbers should +be monotonous increasing according to this ordering. + +Version number sequence +~~~~~~~~~~~~~~~~~~~~~~~ +.... +0.pre.## < 0.01~dev.20YYMMDDhhmm < 0.01 < 0.99 < 1.0~dev.20YYMMDDhhmm < 1.0 < 1.0.1 +.... + +Specifications +~~~~~~~~~~~~~~ +A *tagged build* is made whenever there is a feature change tangible for users. +This might just be a *dev release*. Contrary to this, a *published release* is +a build expected to be installed and used by the users. Amongst the published +releases, we distinguish *major* and *minor* and *bugfix* releases. + +- before we reach _alpha_ status, we don't create any real releases, just + tagged preview builds from time to time. The criteria for reaching alpha + status are defined on the roadmap. + +- during _alpha_ and _beta_ status, we don't differentiate our releases; + they are just numbered consecutively with 2 digits (to start with). A + release is made whenever there is something significant new or otherwise + interesting to try out for the users. + +- besides the releases, we create *development snapshot releases*, which + are just _tagged builds_. + + * Not every build/check-in gets promoted to such a tagged build; + rather there needs to be any reason from the users point of view, + e.g. a bugfix we expect to be tried out at least by _someone_. + + * these _development snapshots_ are an _anticipation_ of the + upcoming next release and thus get a numbering _derived_ from this + _next_ release (not the previous one). + + * dev snapshots use a _timestamp_ attached with a '~' (tilde char). + It is common practice to order a tilde _below_ the release it is + attached to (and debian follows this practice) + +- when we decide the application to be stable enough for real use and + past the _beta_ phase, we switch over to the usual 3-digit version numbering. + + * _major_ releases start with 1.0 and feature high impact changes, usually linked + to some significant breakage of compatibility or some other disruptive event. + + * _minor_ releases may include some new features, but can be considered + evolutionary. Their numbers are incremented on the second digit, like + 1.1, 1.2, 1.3, 1.4, .... + + * _bugfix_ releases are created when we have serious bugfixes to publish, + without any real new features. + +- similar to the practice established in pre-1.0, we can create series of + development snapshots working against and anticipating the next major/minor + release. We'll do so for those users interested in following the development + more closely. The version numbers for such anticipating snapshots are again + created by attaching a timestamp with a '~' (tilde char). + + +Tasks +~~~~~ +// List what needs to be done to implement this Proposal: + * a debian packaging has been created ([green]#✔#) + * the first version was tagged [,yellow]#0.pre.01# + + +Discussion +~~~~~~~~~~ + +Pros +^^^^ +// add a fact list/enumeration which make this suitable: + * the format of the version numbers classifies the kind of build + * the changes in the scheme where chosen to reflect the changed + dynamics in pre-alpha, beta and post-1.0 + * the anticipating snapshots fit better into the usual habits of + developers: the moment a release is published, it is outdated + and uninteresting. + * this practice with the anticipating snapshots was popularised + in by Apache Maven and works well in practice + + +Cons +^^^^ +// fact list of the known/considered bad implications: + + * this visioning scheme might look overengineered at first sight + + +Alternatives +^^^^^^^^^^^^ +//alternatives: explain alternatives and tell why they are not viable: + +_don't worry -- be happy_ is what developers usually do with version numbering. +Especially _not caring_ for development snapshots might be viable for commercial +products; but users of open source software frequently follow the development +rather directly; thus it's a good idea to have a clear numbering for these +dev snapshots too. + +Alternatively we might consider to use Git SHA-Hashes for the dev builds. +But unfortunately, these are rather long and not very mnemonic. We're better +off just adding them to the changelog (as recommended by Debian policy anyway) + + +Rationale +--------- +//rationale: Give a concise summary why it should be done *this* way: + +Many projects face a lot of confusion and bad reputation when they ``happen to run into'' +more widely published releases without any forethought. Users tend to be confused quickly +and can't be expected to understand the details of the development process. Thus we should +discuss and set up a unambiguous numbering scheme really early -- including the criteria +when to use what version number. + + + +//Conclusion +//---------- +//conclusion: When approbate (this proposal becomes a Final) +// write some conclusions about its process: + + + + +Comments +-------- +//comments: append below + + +//endof_comments: + +'''' +Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview] + diff --git a/doc/devel/template/DIR_INFO b/doc/devel/template/DIR_INFO new file mode 100644 index 000000000..d8329334d --- /dev/null +++ b/doc/devel/template/DIR_INFO @@ -0,0 +1 @@ +skeletons for formal documents diff --git a/doc/devel/template/YYYY-MM-DD-developerMeetingSummary.txt b/doc/devel/template/YYYY-MM-DD-developerMeetingSummary.txt new file mode 100644 index 000000000..64d72138f --- /dev/null +++ b/doc/devel/template/YYYY-MM-DD-developerMeetingSummary.txt @@ -0,0 +1,69 @@ +2012-12-12 Lumiera Developers Meeting +===================================== +:Author: Everyone Else +:Date: 2012-12-12 + +Dec 11, 2012 on #lumiera 20:00 - 23:23 UTC + + +__Participants__ + + * cehteh + * ichthyo + * ... + +_Protocol written by XXXXX_ + + + +Recurring Topics +---------------- +Discussion of open http://www.pipapo.org/pipawiki/Lumiera/DesignProcess[design process] drafts. + + +Prop1 +~~~~~ +link:/documentation/devel/rfc_pending/SomeProposal[descriptive name] +Summary what issues are discussed +..Details.. + +Conclusion:: drop it + + + +Topic 1 +------- +Summary what is discussed + +_cehteh_ points out that... + +_joelholdsworth_ adds.... + + +Conclusion +~~~~~~~~~~ + + * do this + * do that + + + +Next meeting +------------ + +The next meeting will be at Wednesday XX XX 20:00 UTC + + +'''' + + +.-- Discussion of details -- +[caption="☉Transcript☉ "] +---------------------------- +12:51 cehteh key/value pairs +12:51 gmerlin not sure about that +12:51 cehteh i am pretty sure that i want that in lumiera + +( shortened and tidied transcript of some interesting detailed discussions ) +---------------------------- + + diff --git a/doc/devel/template_rfc.sh b/doc/devel/template/new_rfc.sh similarity index 100% rename from doc/devel/template_rfc.sh rename to doc/devel/template/new_rfc.sh diff --git a/doc/technical/index.txt b/doc/technical/index.txt index 845b88346..147751f86 100644 --- a/doc/technical/index.txt +++ b/doc/technical/index.txt @@ -1,10 +1,16 @@ Technical Documentation ======================= +// Menu : prepend child backend +// Menu : prepend child proc +// Menu : prepend child gui +// Menu : prepend child howto +// Menu : prepend child overview + This documentation section contains technical documentation about Lumiera. To -get an overview of all the internals and components, you might want to read -link:innerCore/the_inner_core.html[Lumiera the Inner Core] +get an *overview* of all the internals and components, you might want to read +link:overview.html[Lumiera the Inner Core] == Three Layers diff --git a/doc/technical/infra/index.txt b/doc/technical/infra/index.txt index e993d81e9..f1c903af9 100644 --- a/doc/technical/infra/index.txt +++ b/doc/technical/infra/index.txt @@ -6,8 +6,8 @@ Various details, documentation and other pieces of information regarding the infrastructure of the Lumiera project. This includes the infrastructure used for building and maintaining documentation and website. - * see link::../build/index.html[separate page for the Buildsystem] - * generating the link::MenuGen.html[navigation menu] for the website + * see link:../build/index.html[separate page for the Buildsystem] + * generating the link:MenuGen.html[navigation menu] for the website diff --git a/doc/technical/innerCore/DIR_INFO b/doc/technical/innerCore/DIR_INFO deleted file mode 100644 index 33f29ceb2..000000000 --- a/doc/technical/innerCore/DIR_INFO +++ /dev/null @@ -1,3 +0,0 @@ -Internal Design Overview - -Some rather sketchy document about design decisions and rationales diff --git a/doc/technical/innerCore/the_inner_core.txt b/doc/technical/overview.txt similarity index 98% rename from doc/technical/innerCore/the_inner_core.txt rename to doc/technical/overview.txt index 7bc9712ca..5688d9dad 100644 --- a/doc/technical/innerCore/the_inner_core.txt +++ b/doc/technical/overview.txt @@ -1,12 +1,13 @@ Lumiera: The Inner Core ======================= + [abstract] ****************************************************************************** -The Lumiera Developers have a vision about a modern core for a NLE. Here are -some of the design decisions and rationales in a rather sketchy way explained. -New Developers may find this Document useful to get an idea about how the -different components work together. +The Lumiera Developers have a distinct vision about the core of a modern NLE. +This document outlines some of the basic technical concepts and highlights +the fundamental design decisions. New Developers may find this Document useful +to get an idea about how the different components work together. ****************************************************************************** diff --git a/doc/user/index.txt b/doc/user/index.txt index 726244fa5..6b967999c 100644 --- a/doc/user/index.txt +++ b/doc/user/index.txt @@ -1,8 +1,11 @@ User Documentation ================== +// Menu : prepend child intro +// Menu : attach child 'manual' after 'intro' + * link:manual.html[User Manual] _(planned)_ * The following document might become an introductory overview: + - link:outerSpace/lumiera_from_outer_space.html[Lumiera (as seen) from Outer Space] - * link:outerSpace/Glossary.html[Glossary of common terms] + link:intro/intro.html[Lumiera (as seen) from Outer Space] + * link:intro/Glossary.html[Glossary of common terms] diff --git a/doc/user/outerSpace/Glossary.txt b/doc/user/intro/Glossary.txt similarity index 100% rename from doc/user/outerSpace/Glossary.txt rename to doc/user/intro/Glossary.txt diff --git a/doc/user/outerSpace/lumiera_from_outer_space.txt b/doc/user/intro/intro.txt similarity index 99% rename from doc/user/outerSpace/lumiera_from_outer_space.txt rename to doc/user/intro/intro.txt index 397647a7d..1bc008b7c 100644 --- a/doc/user/outerSpace/lumiera_from_outer_space.txt +++ b/doc/user/intro/intro.txt @@ -1,6 +1,7 @@ Lumiera (as seen) from Outer Space ================================== -Christian Thäter +:Author: Christian Thäter ct@pipapo.org +:Date: Summer 2010 [abstract] diff --git a/doc/user/outerSpace/lumiera_big_graph.svg b/doc/user/intro/lumiera_big_graph.svg similarity index 100% rename from doc/user/outerSpace/lumiera_big_graph.svg rename to doc/user/intro/lumiera_big_graph.svg diff --git a/doc/user/outerSpace/lumiera_screenshot.png b/doc/user/intro/lumiera_screenshot.png similarity index 100% rename from doc/user/outerSpace/lumiera_screenshot.png rename to doc/user/intro/lumiera_screenshot.png diff --git a/doc/user/tutorials/building.txt b/doc/user/tutorials/building.txt index cba1a38ed..02af10630 100644 --- a/doc/user/tutorials/building.txt +++ b/doc/user/tutorials/building.txt @@ -77,7 +77,7 @@ mkdir build cd build ../configure make -make install +sudo make install ------------------------------------------------------------ Installing GDL @@ -88,8 +88,11 @@ but we contributed some improvements, which are only available in the very recent development versions of GDL. Thus, for now we created a special package, which doesn't interfere with an existing (older) installation of GDL. -Ubuntu 9.04 note: intltool-update is not patched, you must add -/usr/share/intltool-debian/ to get the gdl-package to configure correctly (JSC). +Ubuntu 9.04 note:: + intltool-update is not patched, you must add +/usr/share/intltool-debian/+ + to get the gdl-package to configure correctly (JSC). +Ubuntu 10.10 note:: + you need to install the +intltool+ package from the standard ubuntu repository ------------------------------------------------------------ git clone git://git.lumiera.org/gdl-package @@ -135,14 +138,11 @@ or similar. If any if this libs are not listed, investigate why before continuin Building Lumiera ---------------- -Lumiera has two maintained (and equivalent) build systems: *scons* and -*autotools*. You can pick the one you feel more comfortable with. - -When trying to build a development version of Lumiera, it might well be that at -times one of the builds doesn't work temporarily. It is always a good idea to -check the current build stats from our *builddrone*, which automatically builds -the latest version from master repository. + Please have a look at this -http://lumiera.org/builddrone/table.html[current build stats]-page. +Up to now, Lumiera has had two maintained (and equivalent) build systems: *scons* and +*autotools*. (Note 3/2011: Right now, the autotools build is broken. It is always a good +idea to check the current build stats from our *builddrone*, which automatically builds +the latest version from master repository. Please have a look at this +http://lumiera.org/builddrone/table.html[current build stats]-page.) Next, after having built and installed the prerequisite libraries, go into the _workspace directory_ to retrieve the Lumiera source code and build it. @@ -159,7 +159,7 @@ scons ----------------- + - * alternatively, if you prefer building with *autotools*: + * alternatively, if you prefer building with *autotools* _(not working currently 3/11)_: + ----------------- git clone git://git.lumiera.org/LUMIERA @@ -192,3 +192,12 @@ cd bin You should see something like (screenshot from 1/2009): image:/media/img/design.gui/screenshot090124-resources.jpg[] + + +What's next? +------------ +If you're a coder, maybe you've found something to improve...? + +Contributing to Lumiera is made easy, thanks to *Git* + +-> Tutorial link:contributing.html[Contributing to Lumiera coding] + diff --git a/doc/user/tutorials/contributing.txt b/doc/user/tutorials/contributing.txt index e7ff9e4ec..df10c1a0d 100644 --- a/doc/user/tutorials/contributing.txt +++ b/doc/user/tutorials/contributing.txt @@ -1,20 +1,27 @@ Contributing to Lumiera ======================= -Nothing is easier, follow the -http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[the basic -instructions], notably the following parts: +The Lumiera project uses an infrastructure based on *Git*, the distibuted +sourcecode management software. This deliberately places the barrier for +contributing very low: No formal ``commit right'' is necessary; you can +start right away and present your first results in the _mob repository_. + +For starters, follow the +http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic +instructions] for using Git, notably the following parts: ------------------------------------------------------------ $ git config --global user.name "Your Name Comes Here" $ git config --global user.email you@yourdomain.example.com ------------------------------------------------------------ -Then you are ready to go, you can edit and commit the lumiera code locally in -your cloned repository. Please do small commits which fix/improve only one -single thing and use meaningful commit messages. +If you followed the link:building.html[building-lumiera tutorial], you created +already a local clone of the Lumiera repository. So you are ready to go, +you can edit build and commit your changes to the lumiera code locally in +your cloned repository. Please commit frequently, do small commits which +fix/improve only one single thing and use meaningful commit messages. -Check that you didn't break anything, by running the testsuite (see above) +Check that you didn't break anything, by running the testsuite. Finally you can push your changes to the lumiera server to the 'mob' repository: @@ -24,3 +31,5 @@ $ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME This creates a new branch 'YOURNAME' on the mob repository. Then you notify the other devs on the mailinglist and they may merge your code into the mainline. + +