Differences between revisions 24 and 61 (spanning 37 versions)
Revision 24 as of 2008-03-10 10:18:03
Size: 5015
Editor: Mac
Comment:
Revision 61 as of 2021-06-14 22:00:53
Size: 10491
Editor: GuillemJover
Comment: Add 1.20.x branch
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
= Git usage in the dpkg team = = git usage in the dpkg team =

Recommendations for handling the [[https://en.wikipedia.org/wiki/Git_%28software%29|git]] repository.
Line 7: Line 9:
   * {{{git clone ssh://git.debian.org/git/dpkg/dpkg.git}}}
   * See ["Alioth/SSH"] for instructions to configure your ["SSH"] access.
   * Check the ["Alioth/FAQ"] if you want to verify the public SSH host key.
 * For anonymous: {{{git clone git://git.debian.org/git/dpkg/dpkg.git}}}
   * {{{git clone ssh://git.dpkg.org/git-dpkg/dpkg/dpkg.git}}}
 * For anonymous: {{{git clone https://git.dpkg.org/git/dpkg/dpkg.git}}}
 * Web view: https://git.dpkg.org/cgit/dpkg/dpkg.git
 * Private repositories of current maintainers:
   * Guillem Jover: {{{https://git.hadrons.org/git/debian/dpkg/dpkg.git}}} ([[https://git.hadrons.org/cgit/debian/dpkg/dpkg.git|web]])

== Public branches ==

 * In the main repository we have the following branches:
   * main: Main development tree.
   * sid: Bug fixes only branch (used when important fixes have to be pushed out before the end of the current development cycle).
   * 1.20.x: Branch corresponding to the Debian bullseye release.
   * 1.19.x: Branch corresponding to the Debian buster release.
   * 1.18.x: Branch corresponding to the Debian stretch release.
   * 1.17.x: Branch corresponding to the Debian jessie release.
   * 1.16.x: Branch corresponding to the Debian wheezy release.
   * 1.15.x: Branch corresponding to the Debian squeeze release.
   * 1.14.x: Branch corresponding to the Debian lenny release.
   * 1.13.x: Branch corresponding to the Debian etch release.
   * jessie, wheezy, squeeze, lenny, etch, stretch, buster: Symbolic reference branches for the corresponding Debian release.
   * next/*: Branches with prospective changes to be merged into the respective parents.
 * In the private repositories of maintainers, you might find other topic branches. Beware that those prefixed with "pu/" are "proposed-updates" that can be rebased at any time, don't use them for long-lived work.

== Commit messages ==

All changes are now described in the commit messages, __debian/changelog__ should not be generally changed as part of a normal commit.
When writing commit messages, these need to follow a specific format that the {{{gen-changelog}}} tool can understand to generate the __debian/changelog__ contents:

{{{
possible-subsystem: Short summary

The rest is the long description. It explains the change in more
details and gives the rationale associated to it. You can be as
verbose as you want.

Possible-Metafield: meta-values
}}}

When committing someone else's work it's important to give proper attribution, so please use {{{git commit --author "Person Name <person@example.org>"}}} to properly attribute the change.

The '''possible-subsystem''' can be a comma separated list of entries matching following regexes:
  * ''arch'': Architecture support.
  * ''Dpkg.*'': Perl modules.
  * ''doc|man'': Documentation (either doc/ or man/).
  * ''build'': Build system.
  * ''debian'': Packaing for dpkg itself.
  * ''test|t'': Test suite.
  * ''po'': Localization.

The '''Possible-Metafield''' can be one of the following:
  * {{{Stable-Candidate}}}: For commits that are candidates to be cherry-picked into one stable branch. Its contents are a space separated list of numeric branch names in the form N.M.x, such as '''1.18.x'''.
  * {{{Closes}}}: The number of the bug(s) this commit fixes/closes. This should follow the usual __debian/changelog__ format of '''#123455'''.
  * {{{Fixes}}}: The number of the bug(s) this commit fixes, but not completely so it should not be closed. Usually when fully fixing an issue requires multiple changes. Same format as {{{Closes}}}.
  * {{{Co-Author}}}: When someone else participated in the creation of the commit in somewhat equal measure as the Author.
  * {{{Improved-by}}}: When someone else provided a tiny fix to this commit.
  * {{{Based-on-patch-by}}}: When someone else created this commit, but got modified substantially to the point that attributing to the other person would be wrong.
  * {{{Thanks-to}}}: When someone else reported how to fix an issue, but did not provide an actual patch to fix it.
  * {{{Reviewed-by}}}: When someone else reviewed the commit.
  * {{{Acked-by}}}: When someone else ACKed the commit (the design choices, the implications, etc), but did not necessarily review it.
  * {{{Tested-by}}}: When someone else tested the commit.
  * {{{Bisected-by}}}: When someone else did a git bisect to track the offending commit this one fixes.
  * {{{Warned-by}}}: When something (a tool) warned about the issue being fixed in the commit.
  * {{{Reported-by}}}: When someone else reported something to be fixed/changed outside of the Debian BTS, or when the bug report included substantial substance to be worth acknowledging the reporting effort.
  * {{{Requested-by}}}: When someone else requested the change.
  * {{{Suggested-by}}}: When someone else suggested the change.
  * {{{Required-by}}}: When something else requires this commit (bug report, package, transition).
  * {{{Spotted-by}}}: When someone else spotted a problem where its fix was self-evident.
  * {{{Prompted-by}}}: When the creation of this commit was indirectly prompted by a discussion by this entity (human or not).
  * {{{Analysis-by}}}: When someone else analyzed or diagnosed the problem.
  * {{{Designed-by}}}: When someone else designed what is being implemented in the commit.
  * {{{Naming-by}}}: When someone else provided the naming for what is implemented in the commit.
  * {{{Ref}}}: For external references, to bug reports, mailing list discussions, web sites, etc.
  * {{{Changelog}}}: To control the __debian/changelog__ generation, with one ore more of the following values:
    * silent|skip|ignore: For commits that should not be included in the __debian/changelog__ output.
    * verbose|full: For commits that should include all their commit message in the __debian/changelog__ output.
    * internal: For code internals that are not supposed to affect the API/ABI of the code/objects.
    * porting: For portability changes.
Line 14: Line 89:
 * Do not forget to let ["Git"] know who you are: {{{git config user.name "John Doe" && git config user.email my.email@addre.ss}}} (you can also use the {{{--global}}} option if you want to configure it the same for all git repositories)
 * When you write commit messages, try to follow the recommended format:
{{{
First line should be a small summary

* src/file.c (foo): Made the foo() function check bla to avoid stuff.
* src/other.c: Fixed usage of foo() to match the previous change.
}}}
 The extended description should follow the [http://www.gnu.org/prep/standards/html_node/Change-Logs.html GNU ChangeLog format].
 *
If you're working on a patch that will take some time to be merged, better work on it in a private topic branch that you can rebase (later and as many times as you want) before merging it in the master branch and pushing it. This will avoid cluttering the history with merge commits.
 * Use git 1.5.x at least. If you run etch there are backports on [http://www.backports.org backports.org].
 * Do not forget to let git know who you are: {{{git config user.name "Person Name" && git config user.email person@example.org}}} (you can also use the {{{--global}}} option if you want to configure it the same for all git repositories)
 * If you are working on a patch that will take some time to be merged, better work on it in a private topic branch that you can rebase (later and as many times as you want) before merging it in the main branch and pushing it. This will avoid cluttering the history with merge commits.
Line 29: Line 95:
 * Finalize the changelogs, update the version in configure.ac, commit the changes.
   * {{{ git commit -a -m "Release <version>" }}}
 * Finalize the changelogs, commit the changes.
   * {{{./gen-changelog}}}
  * {{{dch -r }}}
   * {{{
git commit -a -m "Release <version>"}}}
Line 34: Line 102:
   * {{{autoreconf -f -i; ./configure; make distcheck}}}    * {{{git clean -Xdf}}}
* {{{autoreconf -f -i; ./configure; DPKG_DEVEL_MODE=1 make distcheck}}}
Line 36: Line 105:
   * {{{dpkg-buildpackage -us -uc}}}
 * In general, install the resulting packages and rebuild (this ensures the generated packages are accepted by the archive).
   * {{{dpkg-buildpackage --changes-option=-S}}}
 * Run the autopkgtest suite.
   * {{{sadt -v 2>&1 | tee ../dpkg-autopkgtest-<version>.log}}}
Line 37: Line 111:
   * {{{git push}}}
* {{{git push origin refs/tags/<version>}}}
   * {{{git push origin main <version>}}}
Line 40: Line 113:
   * For possibly disruptive or big changes consider uploading just after the buildd chroots have been upgraded, which currently happens on Wed and Sun at 22:13 UTC (see [[https://salsa.debian.org/dsa-team/mirror/dsa-puppet/blob/master/modules/buildd/manifests/init.pp#L37|puppet definition surroundings]]).
Line 41: Line 115:
 * For a release from the stable branch:
   * Switch to the master branch
   * Merge the stable branch (fix conflicts on changelogs).
 * For a release from the main branch:
   * Start a new version:
     * On debian/changelog, '<version>' and suite UNRELEASED (dch -i should do).
Line 46: Line 120:
 * For a release from the master branch:
   * Start a new version:
     * On configure.ac, use '<version>~'.
     * On debian/changelog, '<version>' and suite UNRELEASED (dch -i should do).
 * For a release from the sid branch:
   * Switch to the main branch.
   * Generate the changelog: {{{./gen-changelog}}}
Line 57: Line 130:
   * Tell Git who you are: {{{git config user.name "John Doe" && git config user.email my.email@addre.ss}}}
 * To update the repository use the commands: {{{git fetch && git rebase origin/master}}}
 * Once you finished your work use the following commands to commit and push your changes:
   * Tell Git who you are: {{{git config user.name "Person Name" && git config user.email person@example.org}}}
   * Enable rebases during pulls: {{{git config pull.rebase true}}}
   * If updating for sid:
     * Use origin/main as <remote>.
   * If updating for buster:
     * Switch to that branch: {{{git checkout -b 1.19.x origin/1.19.x}}}
     * Use origin/1.19.x as <remote>.
   * If updating for stretch:
     * Switch to that branch: {{{git checkout -b 1.18.x origin/1.18.x}}}
     * Use origin/1.18.x as <remote>.
 * To update the repository use the commands: {{{git pull <remote>}}}
 * Once you have finished your work use the following commands to commit and push your changes:
Line 64: Line 146:
If the {{{git push}}} fails, redo the command {{{git fetch && git rebase origin/master}}} and try again. Note that {{{git rebase}}} can be interrupted if there's a conflict between your work and the changes made on the remote repository. In that case, fix the conflicts by editing the conflicted files, then {{{git add <conflicted files>}}} and ask the rebase process to continue with {{{git rebase --continue}}}. Once it's over, {{{git push}}} should work. If the {{{git push}}} fails, redo the command {{{git pull <remote>}}} and try again. Note that the rebase from the {{{git pull}}} can be interrupted if there's a conflict between your work and the changes made on the remote repository. In that case, fix the conflicts by editing the conflicted files, then {{{git add <conflicted files>}}} and ask the rebase process to continue with {{{git rebase --continue}}}. Once it is over, {{{git push}}} should work.
Line 66: Line 148:
<!> Git, as a distributed VCS, allows you to make multiple commits without pushing your changes back, please avoid that if possible. We advise you to not multiply commits uselessly because they clutter the historical log and it's more difficult to see important changes on the code (instead of the translations). If you have multiple commits waiting to be pushed, Git offers you a possibility to "merge" them in a single commit. Proceed as following:
 * {{{git rebase -i origin/master}}}
 * You get a list of your own commits that are going to be rebased, each line starts with {{{pick}}}. You have top edit that list so that the first line contains a {{{pick}}} command and the subsequent one contain a {{{squash}}} command. See example below:
Before:
{{{
pick 7ce2b6c Log message of the first commit
pick 2fbd2c4 Log message of the second commit
pick 9d3196a Log message of the third commit
}}}
After:
{{{
pick 7ce2b6c Log message of the first commit
squash 2fbd2c4 Log message of the second commit
squash 9d3196a Log message of the third commit
}}}
 * Once you save the file and exit the editor, the process starts and you'll soon be asked to provide a new log message for the single commit that will replaces the multiples ones.
 * When it's over, you can proceed to push the changes.
<!> git, as a distributed VCS, allows you to make multiple commits without pushing your changes back, please avoid that if possible. We advise you to not multiply commits uselessly because they clutter the historical log and it's more difficult to see important changes on the code (instead of repeated commits). If you have multiple commits waiting to be pushed, git offers you a possibility to "merge" them in a single commit. Proceed as follows (we assume you are on the branch where you did the multiple commits, all the changes are already committed, and the branch is named $BRANCH):
 * {{{git branch -f l10n}}} (create a new branch l10n containing all your changes, remove any preexisting l10n branch)
 * {{{git reset --hard origin/$BRANCH}}} (drop your changes in the current branch)
 * {{{git merge --squash l10n}}} (merge your changes in a single commit, you have to edit the commit message)
 * You can proceed to push the changes.
Line 86: Line 155:

EddyP: Wouldn't it be easier to advice translators who want to use several local commits, to use a local branch, and at the end {{{git checkout master && git merge --squash translationbranch}}} instead of the complicated file editing?
CategoryGit

git usage in the dpkg team

Recommendations for handling the git repository.

URLs

  • For committers:
    • git clone ssh://git.dpkg.org/git-dpkg/dpkg/dpkg.git

  • For anonymous: git clone https://git.dpkg.org/git/dpkg/dpkg.git

  • Web view: https://git.dpkg.org/cgit/dpkg/dpkg.git

  • Private repositories of current maintainers:
    • Guillem Jover: https://git.hadrons.org/git/debian/dpkg/dpkg.git (web)

Public branches

  • In the main repository we have the following branches:
    • main: Main development tree.
    • sid: Bug fixes only branch (used when important fixes have to be pushed out before the end of the current development cycle).
    • 1.20.x: Branch corresponding to the Debian bullseye release.
    • 1.19.x: Branch corresponding to the Debian buster release.
    • 1.18.x: Branch corresponding to the Debian stretch release.
    • 1.17.x: Branch corresponding to the Debian jessie release.
    • 1.16.x: Branch corresponding to the Debian wheezy release.
    • 1.15.x: Branch corresponding to the Debian squeeze release.
    • 1.14.x: Branch corresponding to the Debian lenny release.
    • 1.13.x: Branch corresponding to the Debian etch release.
    • jessie, wheezy, squeeze, lenny, etch, stretch, buster: Symbolic reference branches for the corresponding Debian release.
    • next/*: Branches with prospective changes to be merged into the respective parents.
  • In the private repositories of maintainers, you might find other topic branches. Beware that those prefixed with "pu/" are "proposed-updates" that can be rebased at any time, don't use them for long-lived work.

Commit messages

All changes are now described in the commit messages, debian/changelog should not be generally changed as part of a normal commit. When writing commit messages, these need to follow a specific format that the gen-changelog tool can understand to generate the debian/changelog contents:

possible-subsystem: Short summary

The rest is the long description. It explains the change in more
details and gives the rationale associated to it. You can be as
verbose as you want.

Possible-Metafield: meta-values

When committing someone else's work it's important to give proper attribution, so please use git commit --author "Person Name <person@example.org>" to properly attribute the change.

The possible-subsystem can be a comma separated list of entries matching following regexes:

  • arch: Architecture support.

  • Dpkg.*: Perl modules.

  • doc|man: Documentation (either doc/ or man/).

  • build: Build system.

  • debian: Packaing for dpkg itself.

  • test|t: Test suite.

  • po: Localization.

The Possible-Metafield can be one of the following:

  • Stable-Candidate: For commits that are candidates to be cherry-picked into one stable branch. Its contents are a space separated list of numeric branch names in the form N.M.x, such as 1.18.x.

  • Closes: The number of the bug(s) this commit fixes/closes. This should follow the usual debian/changelog format of #123455.

  • Fixes: The number of the bug(s) this commit fixes, but not completely so it should not be closed. Usually when fully fixing an issue requires multiple changes. Same format as Closes.

  • Co-Author: When someone else participated in the creation of the commit in somewhat equal measure as the Author.

  • Improved-by: When someone else provided a tiny fix to this commit.

  • Based-on-patch-by: When someone else created this commit, but got modified substantially to the point that attributing to the other person would be wrong.

  • Thanks-to: When someone else reported how to fix an issue, but did not provide an actual patch to fix it.

  • Reviewed-by: When someone else reviewed the commit.

  • Acked-by: When someone else ACKed the commit (the design choices, the implications, etc), but did not necessarily review it.

  • Tested-by: When someone else tested the commit.

  • Bisected-by: When someone else did a git bisect to track the offending commit this one fixes.

  • Warned-by: When something (a tool) warned about the issue being fixed in the commit.

  • Reported-by: When someone else reported something to be fixed/changed outside of the Debian BTS, or when the bug report included substantial substance to be worth acknowledging the reporting effort.

  • Requested-by: When someone else requested the change.

  • Suggested-by: When someone else suggested the change.

  • Required-by: When something else requires this commit (bug report, package, transition).

  • Spotted-by: When someone else spotted a problem where its fix was self-evident.

  • Prompted-by: When the creation of this commit was indirectly prompted by a discussion by this entity (human or not).

  • Analysis-by: When someone else analyzed or diagnosed the problem.

  • Designed-by: When someone else designed what is being implemented in the commit.

  • Naming-by: When someone else provided the naming for what is implemented in the commit.

  • Ref: For external references, to bug reports, mailing list discussions, web sites, etc.

  • Changelog: To control the debian/changelog generation, with one ore more of the following values:

    • silent|skip|ignore: For commits that should not be included in the debian/changelog output.

    • verbose|full: For commits that should include all their commit message in the debian/changelog output.

    • internal: For code internals that are not supposed to affect the API/ABI of the code/objects.
    • porting: For portability changes.

Generic recommendations

  • Do not forget to let git know who you are: git config user.name "Person Name" && git config user.email person@example.org (you can also use the --global option if you want to configure it the same for all git repositories)

  • If you are working on a patch that will take some time to be merged, better work on it in a private topic branch that you can rebase (later and as many times as you want) before merging it in the main branch and pushing it. This will avoid cluttering the history with merge commits.

How to release

  • Verify that you're in sync with the remote repository.
  • Finalize the changelogs, commit the changes.
    • ./gen-changelog

    • dch -r 

    • git commit -a -m "Release <version>"

  • Create a signed tag:
    • git tag -m "Release <version>" -s <version>

  • Generate a source tarball:
    • git clean -Xdf

    • autoreconf -f -i; ./configure; DPKG_DEVEL_MODE=1 make distcheck

  • Do the real build based on the generated tarball.
    • dpkg-buildpackage -us -uc

  • In general, install the resulting packages and rebuild (this ensures the generated packages are accepted by the archive).
    • dpkg-buildpackage --changes-option=-S

  • Run the autopkgtest suite.
    • sadt -v 2>&1 | tee ../dpkg-autopkgtest-<version>.log

  • Push stuff to the remote repository:
    • git push origin main <version>

  • Upload to Debian.
    • For possibly disruptive or big changes consider uploading just after the buildd chroots have been upgraded, which currently happens on Wed and Sun at 22:13 UTC (see puppet definition surroundings).

  • For a release from the main branch:
    • Start a new version:
      • On debian/changelog, '<version>' and suite UNRELEASED (dch -i should do).

    • Commit and push.
  • For a release from the sid branch:
    • Switch to the main branch.
    • Generate the changelog: ./gen-changelog

    • Commit and push.

For translators

  • To setup the repository:
    • Clone the repository as above.
    • Enable the pre-commit hook with chmod +x dpkg/.git/hooks/pre-commit (this will prevent committing conflicts by error)

    • Tell Git who you are: git config user.name "Person Name" && git config user.email person@example.org

    • Enable rebases during pulls: git config pull.rebase true

    • If updating for sid:
      • Use origin/main as <remote>.

    • If updating for buster:
      • Switch to that branch: git checkout -b 1.19.x origin/1.19.x

      • Use origin/1.19.x as <remote>.

    • If updating for stretch:
      • Switch to that branch: git checkout -b 1.18.x origin/1.18.x

      • Use origin/1.18.x as <remote>.

  • To update the repository use the commands: git pull <remote>

  • Once you have finished your work use the following commands to commit and push your changes:
    • git add <list of modified files>

    • git commit

    • git push

If the git push fails, redo the command git pull <remote> and try again. Note that the rebase from the git pull can be interrupted if there's a conflict between your work and the changes made on the remote repository. In that case, fix the conflicts by editing the conflicted files, then git add <conflicted files> and ask the rebase process to continue with git rebase --continue. Once it is over, git push should work.

<!> git, as a distributed VCS, allows you to make multiple commits without pushing your changes back, please avoid that if possible. We advise you to not multiply commits uselessly because they clutter the historical log and it's more difficult to see important changes on the code (instead of repeated commits). If you have multiple commits waiting to be pushed, git offers you a possibility to "merge" them in a single commit. Proceed as follows (we assume you are on the branch where you did the multiple commits, all the changes are already committed, and the branch is named $BRANCH):

  • git branch -f l10n (create a new branch l10n containing all your changes, remove any preexisting l10n branch)

  • git reset --hard origin/$BRANCH (drop your changes in the current branch)

  • git merge --squash l10n (merge your changes in a single commit, you have to edit the commit message)

  • You can proceed to push the changes.


CategoryGit