Carl Sorensen wrote:> As I think more about this, I wonder if there should be a
> short and sweet summary for experienced Linux developers,
> followed by a gentle (and longer) introduction for the
> Windows guys.
Actually, I'm thinking there should be a short and sweet
summary for the GUI-based contributors, followed by a
different (and longer) introduction for the Git-based
developers. I think most of the essentials will be visible
just by skipping the paragraphs (which wouldn't be _that_
long) and looking only at the command-line examples, which
would have everything the experienced devs would need.
**********
Some more thoughts about restructuring the CG... I finally
looked at the lilycontrib app and, well it's pretty awesome.
Has anyone written any documentation for it? I could
probably do it if nobody has yet, since I'm already looking
at the rest of the CG.
Anyway, regarding comments about `short and sweet' vs.
`diluted with fluff'... I'm writing some text intended for
serious would-be developers that makes no assumptions about
previous development experience. It won't be fluff (I'm
aiming for clarity not length), and it won't be required
reading for GUI contributors. But it will explain (with
modest clarity, I hope) some of the currently missing
elements involved that may be common knowledge among more
experienced developers.
If I organize the chapters efficiently, this text would be
in a place where it won't scare away GUI contributors with
details they don't need. But these `details' will be
valuable to those interested in a deeper level of
development involvement.
I feel that it has taken me longer than it should have to
get familiar with some of the basics of compiling, so this
text would ideally reduce the confusion time for new
developers. The idea is not just to get more contributors,
but to make it easier for more contributors to become good
developers.
I've attached an updated (but still unfinished) index
proposal. The less detailed version follows below.
Let me know if you have objections to the outline. Also,
the introduction that I first proposed* would be changed to
more clearly reflect the options available (ie. Graham's
insistence that "you don't need Git to contribute").
Furthermore, some of the `scary details' would be removed
from the introduction and moved to the `Using Git' or
`Compiling' chapters.
*http://lists.gnu.org/archive/html/lilypond-devel/2009-12/txt0Sx9cyLDKu.txt
One final note about the current proposal: Chapter 3 `Using
Git' looks like it'll be quite long this way. I'm
considering splitting it into two chapters, but I've not
made up my mind about it.
Comments appreciated.
- Mark
1. Introduction to contributing
2. Using the `lilycontrib' GUI
3. Using Git
4. Compiling
5. Documentation work (3)
6. Website work (4)
7. LSR work (5)
8. Issues (6)
9. Regression tests (7)
10. Programming work (8)
11. Release work (9)
A. GNU Free Documentation License (A)
1. Introduction to contributing
2. Using the `lilycontrib' GUI
3. Using Git
3.1 Starting with Git
3.1.1 Installing Git
3.1.2 Initializing a repository
3.1.3 Configuring Git
* Global settings (1.1.2)
* Repository settings
3.2 Downloading branches
3.2.1 LilyPond repository sources (1.1.6)
3.2.2 The `master' branch (1.1.3)
3.2.3 The `lilypond/translation' branch (1.1.4)
3.2.4 Other branches (1.1.5)
3.3 Basic procedures
3.3.1 Staying current
* Pulling (1.2.1, .2)
* Resolving conflicts (1.2.3)
3.3.2 Working with branches (1.4.2)
* Creating and removing branches
* Listing branches
* Checking out branches
* Merging branches
3.3.3 Modifying source files
* Making commits
* Formatting patches (1.3.1)
3.4 Advanced procedures
3.4.1 Working with remote branches (1.4.3)
3.4.2 Git log (1.4.4)
3.4.3 Applying remote patches (1.4.5)
3.4.4 Pushing to git.sv.gnu.org (1.3.2)
3.5 Git on Windows
3.6 Repository directory structure (1.7)
3.7 Other Git documentation (1.6)
4. Compiling
4.1 Installing build dependencies (2.1.2)
4.1.1 Using `build-dep'
4.1.2 Requirements for compiling LilyPond
4.1.3 Requirements for running LilyPond
4.1.4 Requirements for building documentation
4.2 Configuring `make'
4.2.1 Creating generated files (2.1.1)
4.2.1 Running ./configure (2.1.3)
* Configuring target directories
* Configuring for multiple platforms
4.3 Compiling LilyPond
4.3.1 Using `make' (2.1.3)
4.4 Post-compilation options
4.4.1 Installing from source (2.1.3)
4.4.2 Generating documentation (2.1.4)
(add @ref to building docs w/o compiling)
* Building documentation
* Installing documentation
4.4.3 Testing LilyPond (2.1.5)
4.5 Concurrent stable and development versions (2.2)
4.6 Compiling on Windows (2.3)
5. Documentation work (3)
* `Building documentation without compiling' here?
6. Website work (4)
7. LSR work (5)
8. Issues (6)
9. Regression tests (7)
10. Programming work (8)
11. Release work (9)
A. GNU Free Documentation License (A)
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
