diff options
Diffstat (limited to 'HACKING')
| -rw-r--r-- | HACKING | 103 |
1 files changed, 52 insertions, 51 deletions
@@ -12,16 +12,16 @@ and check everything in. * If you incorporate a change from somebody on the net: - First, if it is a large change, you must make sure they have signed the - appropriate paperwork. - Second, be sure to add their name and email address to THANKS. + - First, if it is a large change, you must make sure they have + signed the appropriate paperwork. + - Second, be sure to add their name and email address to THANKS. * If a change fixes a test, mention the test in the commit message. If a change fixes a bug registered in the Automake debbugs tracker, mention the bug number in the commit message. * If somebody reports a new bug, mention his name in the commit message - and in the test case you write. Put him into THANKS. + that fixes or exposes the bug, and put him into THANKS. * When documenting a non-trivial idiom or example in the manual, be sure to add a test case for it, and to reference such test case from @@ -35,8 +35,7 @@ which should be updated by hand whenever the GPL gets updated (which shouldn't happen that often anyway :-) -* Changes other than bug fixes must be mentioned in NEWS. Important - bug fixes should be mentioned in NEWS, too. +* Changes other than *trivial* bug fixes must be mentioned in NEWS. * Changes which are potentially controversial, require a non-trivial plan, or must be implemented gradually with a roadmap spanning several @@ -51,13 +50,13 @@ ============================================================================ = Naming -* We've adopted the convention that internal AC_SUBSTs should be - named with a leading 'am__', and internally generated targets - should be named with a leading 'am--'. This convention, although - in place from at least February 2001, isn't yet universally used. +* We've adopted the convention that internal AC_SUBSTs and make variables + should be named with a leading 'am__', and internally generated targets + should be named with a leading 'am--'. This convention, although in + place from at least February 2001, isn't yet universally used. But all new code should use it. - We used to use '_am_' as the prefix for an internal AC_SUBST. + We used to use '_am_' as the prefix for an internal AC_SUBSTs. However, it turns out that NEWS-OS 4.2R complains if a Makefile variable begins with the underscore character. Yay for them. I changed the target naming convention just to be safe. @@ -67,12 +66,11 @@ * Always use $(...) and not ${...} -* Use ':', not 'true'. Use 'exit 1', not 'false'. +* Prefer ':' over 'true', mostly for consistency with existing code. -* Use '##' comments liberally. Comment anything even remotely - unusual. +* Use '##' comments liberally. Comment anything even remotely unusual. -* Never use basename or dirname. Instead use sed. +* Never use basename or dirname. Instead, use sed. * Do not use 'cd' within back-quotes, use '$(am__cd)' instead. Otherwise the directory name may be printed, depending on CDPATH. @@ -81,9 +79,9 @@ computed with CDPATH. * For install and uninstall rules, if a loop is required, it should be - silent. Then the body of the loop itself should print each - "important" command it runs. The printed commands should be preceded - by a single space. + silent. Then the body of the loop itself should print each "important" + command it runs. The printed commands should be preceded by a single + space. * Ensure install rules do not create any installation directory where nothing is to be actually installed. See automake bug#11030. @@ -125,18 +123,21 @@ should be added, and ideally, only trivial bugs, recent regressions, or documentation issues should be addressed by them. -* Minor releases can introduce new "safe" features, do non-trivial - but mostly safe code clean-ups, and even add new runtime warnings - (rigorously non-fatal); but they shouldn't include any backward - incompatible change, nor contain any potentially destabilizing - refactoring or sweeping change, nor introduce new features whose - implementation might be liable to cause bugs or regressions in - existing code. - -* Major releases can introduce backward-incompatibilities (albeit - such incompatibilities should be announced well in advance, and - a smooth transition plan prepared for them), and try more risking - and daring refactorings and code cleanups. +* Minor releases can introduce new "safe" features, do non-trivial but + mostly safe code clean-ups, and even add new runtime warnings (rigorously + non-fatal). But they shouldn't include any backward incompatible change, + nor contain any potentially destabilizing refactoring or sweeping change, + nor introduce new features whose implementation might be liable to cause + bugs or regressions in existing code. However, it might be acceptable to + introduce very limited and localized backward-incompatibilities, *only* + if that is necessary to fix non-trivial bugs, address serious performance + issues, or greatly enhance usability. But please, do this sparsely and + rarely! + +* Major releases can introduce backward-incompatibilities (albeit such + incompatibilities should be announced well in advance, and a smooth + transition plan prepared for them), and try more risking and daring + refactorings and code cleanups. * For more information, refer to the extensive discussion associated with automake bug#13578. @@ -152,30 +153,30 @@ latest stable version of Autoconf installed and available early in your PATH. -* The Automake git tree currently carries three basic branches: 'maint', - 'master' and 'next'. +* The Automake git tree currently carries three basic branches: 'micro', + 'maint' and 'master'. -* The 'maint' branch, reserved to changes that should go into the next +* The 'micro' branch, reserved to changes that should go into the next micro release; so it will just see fixes for regressions, trivial bugs, or documentation issues, and no "active" development whatsoever. Since emergency regression-fixing or security releases could be cut from this branch at any time, it should always be kept in a releasable state. -* The 'master' branch is where the development of the next minor release +* The 'maint' branch is where the development of the next minor release takes place. It should be kept in a stable, almost-releasable state, to simplify testing and deploying of new minor version. Note that this is not a hard rule, and such "stability" is not expected to be - absolute (emergency releases are cut from maint anyway). + absolute (emergency releases are cut from the 'micro' branch anyway). -* The 'next' branch is reserved for the development of the next major - release. Experimenting a little here is OK, but don't let the branch - grow too unstable; if you need to do exploratory programming - or over-arching change, you should use a dedicated topic branch, and +* The 'master' branch is reserved for the development of the next major + release. Experimenting a little is OK here, but don't let the branch + grow too unstable; if you need to do exploratory programming or + over-arching change, you should use a dedicated topic branch, and only merge that back once it is reasonably stable. -* The 'maint' branch should be kept regularly merged into the 'master' - branch, and the 'master' branch into the 'next' branch. It is advisable +* The 'micro' branch should be kept regularly merged into the 'maint' + branch, and the 'maint' branch into the 'master' branch. It is advisable to merge only after a set of related commits have been applied, to avoid introducing too much noise in the history. @@ -183,12 +184,12 @@ developments. They should be based off of a common ancestor of all active branches to which the feature should or might be merged later. -* After a new minor release is done, the 'master' branch is to be merged - into the 'maint' branch, and then a "new" 'master' branch created +* After a new minor release is done, the 'maint' branch is to be merged + into the 'micro' branch, and then a "new" 'maint' branch created stemming from the resulting commit. - Similarly, after a new major release is done, the 'next' branch is to - be merged into both the 'master' and 'maint' branch, and then "new" - 'master' and 'next' branches created stemming from the resulting commit. + Similarly, after a new major release is done, the 'master' branch is to + be merged into both the 'micro' and 'maint' branches, and then "new" + 'master' branch created stemming from the resulting commit. * When fixing a bug (especially a long-standing one), it may be useful to commit the fix to a new temporary branch based off the commit that @@ -200,11 +201,11 @@ a later 'git log' gives an indication of which actual patches were merged even when they don't appear early in the list. -* The 'master' and 'maint' branches should not be rewound, i.e., should - always fast-forward, except maybe for privacy issues. For 'next' - (if that will ever be implemented), and for feature branches, the - announcement for the branch should document rewinding policy. If a - topic branch is expected to be rewound, it is good practice to put +* The 'master', 'maint' and 'micro' branches should not be rewound, i.e., + should always fast-forward, except maybe for privacy issues. For + feature branches, the announcement for the branch should document + the rewinding policy. + If a topic branch is expected to be rewound, it is good practice to put it in the 'experimental/*' namespace; for example, a rewindable branch dealing with Vala support could be named like "experimental/vala-work". |