X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=HACKING;h=fdadada41a1576cab7569a24ff70df6888dcc8a5;hb=6d03501bcae9249dd87dad2cb7feb78d5fcfd89a;hp=696638447a3866557ea53343000f7908f21e0016;hpb=a36a8f6e7f52521d3c5d9f382ab5a4e7676b42f1;p=platform%2Fupstream%2Fautomake.git diff --git a/HACKING b/HACKING index 6966384..fdadada 100644 --- a/HACKING +++ b/HACKING @@ -1,10 +1,10 @@ -================================================================ +============================================================================ = This file * This file attempts to describe the rules to use when hacking automake. -================================================================ +============================================================================ = Administrivia * The correct response to most actual bugs is to write a new test case @@ -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,34 +35,42 @@ 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 + releases (either minor or major) should be discussed on the list, + and have a proper entry in the PLANS directory. This entry should be + always committed in the "maint" branch, even if the change it deals + with is only for the master branch, or a topic branch. Usually, in + addition to this, it is useful to open a "wishlist" report on the + Automake debbugs tracker, to keep the idea more visible, and have the + discussions surrounding it easily archived in a central place. + +============================================================================ = 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. -================================================================ +============================================================================ = Editing '.am' files * 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. @@ -71,14 +79,14 @@ 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. -================================================================ +============================================================================ = Editing automake.in and aclocal.in * Indent using GNU style. For historical reasons, the perl code @@ -86,13 +94,58 @@ default), and other portions using the GNU style (cperl-mode's default). Write new code using GNU style. -* Don't use & for function calls, unless required. +* Don't use & for function calls, unless really required. The use of & prevents prototypes from being checked. - Just as above, don't change massively all the code to strip the - &, just convert the old code as you work on it, and write new - code without. -================================================================ +============================================================================ += Automake versioning and compatibility scheme + +* There are three kinds of automake releases: + + - new major releases (e.g., 2.0, 5.0) + - new minor releases (e.g., 1.14, 2.1) + - micro a.k.a. "bug-fixing" releases (e.g., 1.13.2, 2.0.1, 3.5.17). + + A new major release should have the major version number bumped, and + the minor and micro version numbers reset to zero. A new minor release + should have the major version number unchanged, the minor version number + bumped, and the micro version number reset to zero. Finally, a new + micro version should have the major and minor version numbers unchanged, + and the micro version number bumped. + + For example, the first minor version after 1.13.2 will be 1.14; the + first bug-fixing version after 1.14 that will be 1.14.1; the first + new major version after all such releases will be 2.0; the first + bug-fixing version after 2.0 will be 2.0.1; and a further bug-fixing + version after 2.0.1 will be 2.0.2. + +* Micro releases should be just bug-fixing releases; no new features + should be added, and ideally, only trivial bugs, recent regressions, + or documentation issues should be addressed by them. On the other + hand, it's OK to include testsuite work and even testsuite refactoring + in a micro version, since a regression there is not going to annoy or + inconvenience Automake users, but only the Automake developers. + +* 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. + +============================================================================ = Working with git * To regenerate dependent files created by aclocal and automake, @@ -103,22 +156,43 @@ latest stable version of Autoconf installed and available early in your PATH. -* The Automake git tree currently carries two basic branches: 'master' for - the current development, and 'maint' for maintenance and bug fixes. The - maint branch should be kept regularly merged 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. +* The Automake git tree currently carries three basic branches: 'micro', + 'maint' and 'master'. + +* 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 '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 the 'micro' branch anyway). + +* 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 '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. * There may be a number of longer-lived feature branches for new developments. They should be based off of a common ancestor of all active branches to which the feature should or might be merged later. - in the future, we might introduce a special branch named 'next' that - may serve as common ground for feature merging and testing, should - they not yet be ready for master. -* After a major release is done, the master branch is to be merged into - the maint branch, and then a "new" master branch created stemming - from the resulting commit. +* 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 '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 @@ -126,17 +200,19 @@ the active branches descending from the buggy commit. This offers a simple way to fix the bug consistently and effectively. -* For merges from branches other than maint, prefer 'git merge --log' over - plain 'git merge', so that a later 'git log' gives an indication of which - actual patches were merged even when they don't appear early in the list. +* When merging, prefer 'git merge --log' over plain 'git merge', so that + a later 'git log' gives an indication of which actual patches were + merged even when they don't appear early in the list. -* master and release branches should not be rewound, i.e., should always - fast-forward, except maybe for privacy issues. The maint branch should not - be rewound except maybe after retiring a release branch or a new stable - release. For next, and for feature branches, the announcement for the - branch should document rewinding policy. +* 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". -================================================================ +============================================================================ = Writing a good commit message * Here is the general format that Automake's commit messages are expected @@ -148,8 +224,9 @@ Here goes a more detailed explanation of why the commit is needed, - and a general overview of what it does, and how. This section is - optional, but you are expected to provide it more often than not. + and a general overview of what it does, and how. This section + should almost always be provided, possibly only with the expection + of obvious fixes or very trivial changes. And if the detailed explanation is quite long or detailed, you can want to break it in more paragraphs. @@ -166,10 +243,10 @@ -* The is mandatory but for the most - trivial changes, and should follows the GNU guidelines for ChangeLog - entries (described explicitly in the GNU Coding Standards); it might - be something of this sort: +* The should usually be provided (but + for short or trivial changes), and should follow the GNU guidelines + for ChangeLog entries (described explicitly in the GNU Coding + Standards); it might be something of this sort: * some/file (func1): Improved frobnication. (func2): Adjusted accordingly. @@ -197,13 +274,11 @@ ... removed in commit 'v1.11-1674-g02e9072' of 01-01-2012, "dist: ditch support for lzma"... -================================================================ +============================================================================ = Test suite * Use "make check" and "make maintainer-check" liberally. -* Make sure each test file is executable. - * Export the 'keep_testdirs' environment variable to "yes" to keep test directories for successful tests also. @@ -212,7 +287,7 @@ * See file 't/README' for more information. -================================================================ +============================================================================ = Release procedure * The steps outlined here are meant to be followed for alpha and stable @@ -227,15 +302,27 @@ date. The maintainer-only target "update-copyright" can help with this. -* Update NEWS. +* Check NEWS; in particular, ensure that all the relevant differences + with the last release are actually reported. * Update the version number in configure.ac. (The idea is that every other alpha number will be a net release. The repository will always have its own "odd" number so we can easily distinguish net and repo versions.) -* Run this: - ./bootstrap.sh && ./configure && make && make check && make distcheck +* Run these commands, in this order: + + make bootstrap + make check keep_testdirs=yes + make maintainer-check + make distcheck + make check-no-trailing-backslash-in-recipes + make check-cc-no-c-o + + It is also advised to run "git clean -fdx" before invoking the + bootstrap, to ensure a really clean rebuild. However, it must + be done carefully, because that command will remove *all* the + files that are not tracked by git! * Run "make git-tag-release". This will run the maintainer checks, verify that the local git @@ -251,34 +338,53 @@ locations. In case you need to sign with a non-default key, you can use "make GNUPLOADFLAGS='--user KEY' git-upload-release". +* For stable releases you'll have to update the manuals at www.gnu.org. + + - Generate manuals (with the help of the standard gendocs.sh script): + + make web-manual + + The ready-to-be-uploaded manuals (in several formats) will be left + in the 'doc/web-manuals' directory. + + - Commit the updated manuals to web CVS: + + make web-manual-update + + If your local username is different from your username at Savannah, + you'll have to override the 'CVS_USER' make variable accordingly; + for example: + + make web-manual-update CVS_USER=slattarini + + - Check for link errors, fix them, recheck until convergence: + + +* Create an announcement message with "make announcement". Edit the + generated 'announcement' file appropriately, in particularly filling + in by hand any "TODO" left in there. + * Update version number in configure.ac to next alpha number. Re-run ./bootstrap.sh and commit. * Don't forget to "git push" your changes so they appear in the public git tree. -* For stable releases, update the manuals at www.gnu.org: - - Generate manuals: - cd doc - wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs.sh" - wget "http://savannah.gnu.org/cgi-bin/viewcvs/~checkout~/texinfo/texinfo/util/gendocs_template" - sh ./gendocs.sh --email bug-automake@gnu.org automake "GNU Automake" - - copy manuals recursively to web cvs, - - commit. - - Check for link errors, fix them, recheck until convergence: - - -* Send the announcement at least to and - . If the release is a stable one, the announcement - must also go to ; if it is an alpha or beta release, - announcement should be sent also to , to - maximize the possibility of early testing on exotic or proprietary - systems. Finally, copy the announcement into the NEWS feed at +* Send the announcement generated in the earlier steps at least to + and . If the release + is a stable one, the announcement must also go to ; + if it is an alpha or beta release, announcement should be sent also + to , to maximize the possibility of early + testing on exotic or proprietary systems. Finally, copy an abridged + version of the announcement into the NEWS feed at: . + Be sure to link a version to the complete announcement (from + the version you sent to the automake list, as get archived on + ). ----- -Copyright (C) 2003-2012 Free Software Foundation, Inc. +Copyright (C) 2003-2013 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by