From e506ee7e5b4bd9d87299e0e55d5fa43b738c0933 Mon Sep 17 00:00:00 2001 From: Michael Prokop Date: Wed, 16 Jun 2010 17:52:13 +0200 Subject: move maintainer-notes.html to docs/ and install as /usr/share/doc/initramfs-tools/maintainer-notes.html Signed-off-by: Michael Prokop --- docs/maintainer-notes.html | 306 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 306 insertions(+) create mode 100644 docs/maintainer-notes.html (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html new file mode 100644 index 0000000..11149b8 --- /dev/null +++ b/docs/maintainer-notes.html @@ -0,0 +1,306 @@ + + + + +Maintainer documentation for initramfs-tools + + + + + +
+
+ +

Maintainer documentation for initramfs-tools

+ +
+ +

Table of Contents

+ + + +
+ +

1. Definitions

+ +

+ Note: This cheatpage assumes that you are using git-core 1.5.6 or newer. +

+ + + + + +
version:version string
username:name of the alioth account
mailaddress:mailaddress of the user
+ +
^
+
+ +

2. Preparations

+ +
    + +
  1. Install required software (notice: git is named git-core on Debian/stable): +
    +# apt-get install git git-buildpackage dpkg-dev
+
    +
    2. + +
  2. Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for git and git-dch: +
    +% export GIT_AUTHOR_EMAIL=<mailaddress>
+% export DEBEMAIL=<mailaddress>
+% export GIT_COMMITTER_EMAIL=<mailaddress>
+
    +
    3. + +
  3. Checkout repository (anonymous): +
    +% git clone git://git.debian.org/git/kernel/initramfs-tools.git
+% cd initramfs-tools
+
    +
    4. + +
  4. Checkout repository (with developer access): +
    +% git clone ssh://username@git.debian.org/git/kernel/initramfs-tools.git
+% cd initramfs-tools
+
    +
    5. + +
+ +
^
+
+ +

3. Workflow for daily work

+ +

3.1 Implement new features

+ +
    + +
  1. Checkout new branch and switch to it: +
    +% git checkout -b username/short-descr-of-new-feature
+
    +
    2. + +
  2. Hack and commit work: +
    +% $EDITOR $somefile
+% git add $somefile
+% git commit -s
+
    +
    3. + +

    NOTE: Use 'Closes: #BUGID' for closing a bugreport, 'Thanks: Name +<mailaddress>' for giving credits in your commit message. git-dch will use +this information for generating the changelog using the --meta option later +on.

    + +
  3. Finally push your branch to alioth: +
    +% git push origin username/short-descr-of-new-feature
+
    +
    4. + +
+ +

3.2 Merge branches

+ +
    + +
  1. Switch to the branch you want to merge: +
    +% git checkout username/new-feature
+
    +
    2. + +
  2. Rebase to master: +
    +% git rebase master
+
    +
    3. + +
  3. Switch to master branch and merge: +
    +% git checkout master
+% git merge username/new-feature
+
    +
    4. + +
  4. Push: +
    +% git push
+
    +
    5. + +
  5. After branch is merged delete branch on server and locally: +
    +% git push origin :username/short-descr-of-new-feature
+% git branch -d username/short-descr-of-new-feature
+
    +
    6. + +
+ +

3.3 Test specific branch

+ +
    + +
  1. Checkout a specific branch iff branch is not already present locally: +
    +% git checkout -b somename/short-descr-of-new-feature origin/somename/short-descr-of-new-feature
+
    +
    2. + +
  2. Checkout a specific branch iff branch is already present locally: +
    +% git checkout -b somename/short-descr-of-new-feature
+
    +
    3. + +
  3. Adjust debian/changelog accordingly: +
    +git-dch --debian-branch="$(git branch | awk -F\* '/^* / { print $2}' )" --since=$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') -S --id-length=7 --meta
+
    +
    4. + +
  4. Build package: +
    +% git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc
+
    +
+ +
^
+ +

4. Contribute

+ +

TODO / WIP:

+ +
    +
  1. Create patch: +
    +% git format-patch HEAD
+
    +
+ +
^
+ +

5 Releasing new version

+ +
    + +
  1. Creating changelog: + +
    +% git-dch --debian-branch debian --release --since HASH
+
    + +or more dynamically: + +
    +% git-dch --meta --release --since v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') --debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" [--id-length=7] [--full]
+
    + +
    2. + +
  2. Releasing: +
    +% git commit -a -s -m "Releasing debian version version."
+
    +
    3. + +
  3. Tagging: +
    +% git tag -s v"version" -m "release version"
+
    +
    4. + +
  4. Pushing: +
    +% git push
+% git push --tags
+
    +
    5. + +
  5. Build in chroot and upload to ftp-master.
    6. + +
  6. Send mail announcing the new initramfs-tools version with subject +"initramfs-tools $VERSION release" to initramfs@vger.kernel.org, +debian-kernel@lists.debian.org + kernel-team@lists.ubuntu.com - including a +shortlog (generated through "git shortlog $TAG..").
    7. + +
+ +
^
+
+ +

Ressources

+ + + + +
^
+
+ +

Credits

+ +
    +
  • Thanks to Daniel Baumann for his "Maintainer Cheatpage" which inspired this document
    • +
+ +
^
+
+ +

+-- Michael Prokop <mika@debian.org> +

+ +
+ +
+ + + + -- cgit v1.2.3 From d53a83994bfe7a9e1b9278afc4a12f7dca610f3f Mon Sep 17 00:00:00 2001 From: Michael Prokop Date: Thu, 17 Jun 2010 02:18:28 +0200 Subject: maintainer-notes.html: extend contribution section, rewrap + fix git-dch/git-buildpackage commandline Signed-off-by: Michael Prokop --- docs/maintainer-notes.html | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index 11149b8..3bda045 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -193,13 +193,14 @@ on.

  • Adjust debian/changelog accordingly: 
    -git-dch --debian-branch="$(git branch | awk -F\* '/^* / { print $2}' )" --since=$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') -S --id-length=7 --meta
+% git-dch --debian-branch="$(git branch | awk -F\*\   '/^* / { print $2}' )" \
+  --since="$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta
  • Build package: 
    -% git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc
+% git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc
    @@ -207,12 +208,15 @@ on.

    4. Contribute

    -

    TODO / WIP:

    -
    1. Create patch: 
      -% git format-patch HEAD
+% git format-patch -s -p origin/master
+
      + +
    2. Send patch file(s) to maintainers via mail (requires Debian package git-email): +
      +% git send-email --to=initramfs-tools@packages.qa.debian.org $PATCHFILE[S]
    -- cgit v1.2.3 From 6af23c2bb403323fef33e830770c832616a7911b Mon Sep 17 00:00:00 2001 From: Michael Prokop Date: Fri, 18 Jun 2010 11:06:02 +0200 Subject: docs/maintainer-notes: valid XHTML 1.0 Strict document, add section "Build snapshot version", add license note, minor formating cleanups + improvements Signed-off-by: Michael Prokop --- docs/maintainer-notes.html | 122 +++++++++++++++++++++++++++++++-------------- 1 file changed, 84 insertions(+), 38 deletions(-) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index 3bda045..e8d36ea 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -12,8 +12,6 @@ acronym { cursor: help; } body { font-family: "DejaVu Sans", "Bitstream Vera Sans", sans-serif; } pre { background-color: #EEEEEE; border: 1px dashed black; padding: 1em; } div.right { text-align: right; } -red { color: red; } -gray { color: gray; } /*]]>*/ @@ -39,29 +37,34 @@ gray { color: gray; }
  • 3.1 Implement new features
  • 3.2 Merge branches
  • 3.3 Test specific branch
    • +
  • 3.4 Build snapshot version
  • 4. Contribute
    • -
  • 5 Releasing new version
    • -
  • 6 Ressources
    • -
  • 7 Credits
    • - +
  • 5. Release new version
    • +
  • 6. Ressources
    • +
  • 7. Credits
    • +
  • 8. License
    • -

    1. Definitions

    +

    NOTE: The most recent version of this document is available at +docs/maintainer-notes.html in the the git repository +or online at git.debian.org.

    -

    - Note: This cheatpage assumes that you are using git-core 1.5.6 or newer. -

    +
    + +

    1. Definitions

    - - - + + + +
    version:version string
    username:name of the alioth account
    mailaddress:mailaddress of the user
    $mailaddress:mailaddress of the user
    $username:name of the alioth account
    $version:version string
    $yourname:your fullname
    ^
    @@ -79,13 +82,16 @@ gray { color: gray; }
  • Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for git and git-dch: 
    -% export GIT_AUTHOR_EMAIL=<mailaddress>
-% export DEBEMAIL=<mailaddress>
-% export GIT_COMMITTER_EMAIL=<mailaddress>
+export DEBEMAIL=$mailaddress
+export DEBFULLNAME=$yourname
+export GIT_AUTHOR_EMAIL=$mailaddress
+export GIT_AUTHOR_NAME=$yourname
+export GIT_COMMITTER_EMAIL=$mailaddress
+export GIT_COMMITTER_NAME=$yourname
    • -
  • Checkout repository (anonymous): +
  • Checkout repository (anonymous): 
     % git clone git://git.debian.org/git/kernel/initramfs-tools.git
 % cd initramfs-tools
@@ -94,7 +100,7 @@ gray { color: gray; }
 
 
  • Checkout repository (with developer access):
 
    -% git clone ssh://username@git.debian.org/git/kernel/initramfs-tools.git
+% git clone ssh://$username@git.debian.org/git/kernel/initramfs-tools.git
 % cd initramfs-tools
 
    
 
    • 
@@ -112,7 +118,7 @@ gray { color: gray; }
 
 
  • Checkout new branch and switch to it:
 
    -% git checkout -b username/short-descr-of-new-feature
+% git checkout -b $username/short-descr-of-new-feature
 
    
 
    • 
 
@@ -122,16 +128,17 @@ gray { color: gray; }
 % git add $somefile
 % git commit -s
    -
    • -

    NOTE: Use 'Closes: #BUGID' for closing a bugreport, 'Thanks: Name -<mailaddress>' for giving credits in your commit message. git-dch will use +NOTE: Use 'Closes: #BUGID' for closing a bugreport and 'Thanks: Fullname +<mailaddress>' for giving credits in your commit message. git-dch will use this information for generating the changelog using the --meta option later -on.

    +on. + +
  • Finally push your branch to alioth: 
    -% git push origin username/short-descr-of-new-feature
+% git push origin $username/short-descr-of-new-feature
    • @@ -143,7 +150,7 @@ on.

  • Switch to the branch you want to merge: 
    -% git checkout username/new-feature
+% git checkout $username/new-feature
    • @@ -156,7 +163,7 @@ on.

  • Switch to master branch and merge: 
     % git checkout master
-% git merge username/new-feature
+% git merge $username/new-feature
    • @@ -168,8 +175,8 @@ on.

  • After branch is merged delete branch on server and locally: 
    -% git push origin :username/short-descr-of-new-feature
-% git branch -d username/short-descr-of-new-feature
+% git push origin :$username/short-descr-of-new-feature
+% git branch -d $username/short-descr-of-new-feature
    • @@ -202,9 +209,34 @@ on.

     % git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc
    + + + + +
    ^
    +
    + +

    3.4 Build snapshot version

    + +
      + +
    1. Adjust debian/changelog accordingly: +
      +% git-dch --debian-branch="$(git branch | awk -F\*\   '/^* / { print $2}' )" \
+  --since="$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta
+
      +
      2. + +
    2. Build package: +
      +% git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc [-us -uc]
+
      +
      3. +
    ^
    +

    4. Contribute

    @@ -213,23 +245,27 @@ on.

     % git format-patch -s -p origin/master
    +
  • Send patch file(s) to maintainers via mail (requires Debian package git-email): 
     % git send-email --to=initramfs-tools@packages.qa.debian.org $PATCHFILE[S]
    +
    • +
    ^
    +
    -

    5 Releasing new version

    +

    5. Release new version

    1. Creating changelog: 
      -% git-dch --debian-branch debian --release --since HASH
+% git-dch --debian-branch debian --release --since HASH
      or more dynamically: @@ -238,17 +274,21 @@ or more dynamically: % git-dch --meta --release --since v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') --debian-branch="$(git branch | awk -F\*\ '/^* / { print $2}' )" [--id-length=7] [--full] +NOTE: we do not use history based sorting for the changelog entries but +sort them by author (doing that manually when reviewing the changelog, see #586165). +
    2. Releasing: 
      -% git commit -a -s -m "Releasing debian version version."
+% git commit -a -s -m "Releasing version $version."
    3. Tagging: 
      -% git tag -s v"version" -m "release version"
+% git tag -s v"$version" -m "release $version"
      4. @@ -271,7 +311,7 @@ shortlog (generated through "git shortlog $TAG..").
      ^
      -

      Ressources

      +

      6. Ressources

      +
      ^
      +
      + +

      7. Credits

      + +
      ^
      -

      Credits

      +

      8. License

        -
      • Thanks to Daniel Baumann for his "Maintainer Cheatpage" which inspired this document
        • +
      • This document is licensed under GPL v2 or any later version.
      ^

      --- Michael Prokop <mika@debian.org> +-- Michael Prokop <mika@debian.org>

      - - -- cgit v1.2.3 From 22d996c1b3bf29e2b665db695414441ec21c7270 Mon Sep 17 00:00:00 2001 From: maximilian attems Date: Fri, 18 Jun 2010 11:25:03 +0200 Subject: maintainer doc: use git commands without the dash plus minor changes: - initramfs-tools uses master branches. - DEBEMAIL and friends affects devscripts. Signed-off-by: maximilian attems --- docs/maintainer-notes.html | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index e8d36ea..9858201 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -80,7 +80,7 @@ or online at -
    4. Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for git and git-dch: +
    5. Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for git and devscripts (git dch): 
       export DEBEMAIL=$mailaddress
 export DEBFULLNAME=$yourname
@@ -130,7 +130,7 @@ export GIT_COMMITTER_NAME=$yourname
      NOTE: Use 'Closes: #BUGID' for closing a bugreport and 'Thanks: Fullname -<mailaddress>' for giving credits in your commit message. git-dch will use +<mailaddress>' for giving credits in your commit message. git dch will use this information for generating the changelog using the --meta option later on. @@ -200,14 +200,14 @@ on.
    6. Adjust debian/changelog accordingly: 
      -% git-dch --debian-branch="$(git branch | awk -F\*\   '/^* / { print $2}' )" \
+% git dch --debian-branch="$(git branch | awk -F\*\   '/^* / { print $2}' )" \
   --since="$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta
    7. Build package: 
      -% git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc
+% git buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc
      8. @@ -222,14 +222,14 @@ on.
    8. Adjust debian/changelog accordingly: 
      -% git-dch --debian-branch="$(git branch | awk -F\*\   '/^* / { print $2}' )" \
+% git dch --debian-branch="$(git branch | awk -F\*\   '/^* / { print $2}' )" \
   --since="$(dpkg-parsechangelog | awk '/^Version:/ {print $2}')" -S --id-length=7 --meta
    9. Build package: 
      -% git-buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc [-us -uc]
+% git buildpackage --git-debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" -tc [-us -uc]
      10. @@ -265,13 +265,13 @@ on.
    10. Creating changelog: 
      -% git-dch --debian-branch debian --release --since HASH
+% git dch --debian-branch master --release --since HASH
      or more dynamically: 
      -% git-dch --meta --release --since v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') --debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" [--id-length=7] [--full]
+% git dch --meta --release --since v$(dpkg-parsechangelog | awk '/^Version:/ {print $2}') --debian-branch="$(git branch | awk -F\*\  '/^* / { print $2}' )" [--id-length=7] [--full]
      NOTE: we do not use history based sorting for the changelog entries but -- cgit v1.2.3 From 38ee1a01a95be213733d90573edafd1a1363c413 Mon Sep 17 00:00:00 2001 From: Michael Prokop Date: Tue, 22 Jun 2010 10:38:43 +0200 Subject: maintainer-notes: document "git remote prune origin" Thanks: maximilian attems Signed-off-by: Michael Prokop --- docs/maintainer-notes.html | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index 9858201..354dece 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -180,6 +180,13 @@ on.
      11. +
    11. If a branch is removed from the server it will stay locally. You can get of +any stale remote branches locally by executing: +
      +% git remote prune origin
+
      +
      12. +

    3.3 Test specific branch

    -- cgit v1.2.3 From 2390db89c9bcf1f83405098ba9221ae7476187cb Mon Sep 17 00:00:00 2001 From: Michael Prokop Date: Tue, 22 Jun 2010 10:44:34 +0200 Subject: maintainer-notes: use git config instead of environment variables Thanks: Gerfried Fuchs Signed-off-by: Michael Prokop --- docs/maintainer-notes.html | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index 354dece..eeceafd 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -80,14 +80,17 @@ or online at -
  • Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for git and devscripts (git dch): +
  • Set environment variables (e.g. through your ~/.bashrc or ~/.zshrc) for devscripts (git dch): 
     export DEBEMAIL=$mailaddress
-export DEBFULLNAME=$yourname
-export GIT_AUTHOR_EMAIL=$mailaddress
-export GIT_AUTHOR_NAME=$yourname
-export GIT_COMMITTER_EMAIL=$mailaddress
-export GIT_COMMITTER_NAME=$yourname
+export DEBFULLNAME=$yourname
+
    +
    • + +
  • Set user name and email address for git (drop the --global option to use configuration per-repo basis): +
    +% git config --global user.name  "$yourname"
+% git config --global user.email "$mailaddress"
    • -- cgit v1.2.3 From 6bcb867c1cb3082f265dc1c1a60ec72c9dcd90ed Mon Sep 17 00:00:00 2001 From: maximilian attems Date: Thu, 8 Jul 2010 11:34:52 +0200 Subject: Maintainer notes document dev mailinglists we are listening there. :) Signed-off-by: maximilian attems --- docs/maintainer-notes.html | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index eeceafd..ede8550 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -263,6 +263,9 @@ any stale remote branches locally by executing: +
  • The development mailinglists are debian-kernel@lists.debian.org or initramfs@vger.kernel.org. Discussion of eventual features, bugs or patches are more then welcomed there. +
    • +
    ^
    -- cgit v1.2.3 From c85bb1f2d6fcf617775255fbf278358ad2379e95 Mon Sep 17 00:00:00 2001 From: Michael Prokop Date: Thu, 8 Jul 2010 14:40:27 +0200 Subject: some minor rewording of sentences about development mailinglists Signed-off-by: Michael Prokop --- docs/maintainer-notes.html | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index ede8550..fd85e00 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -263,8 +263,11 @@ any stale remote branches locally by executing: -
  • The development mailinglists are debian-kernel@lists.debian.org or initramfs@vger.kernel.org. Discussion of eventual features, bugs or patches are more then welcomed there. -
    • +
  • The development mailinglists are debian-kernel@lists.debian.org +and initramfs@vger.kernel.org. +Discussion of features, bugs and patches are more than welcome on those +lists.
    • -- cgit v1.2.3 From 7c6221d459e765f6ae8f40361727b72b65c88509 Mon Sep 17 00:00:00 2001 From: maximilian attems Date: Thu, 8 Jul 2010 15:03:31 +0200 Subject: maintainer notes: underline that mail to one of the 2 lists is good small wording change. Signed-off-by: maximilian attems --- docs/maintainer-notes.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/maintainer-notes.html') diff --git a/docs/maintainer-notes.html b/docs/maintainer-notes.html index fd85e00..e9cec2d 100644 --- a/docs/maintainer-notes.html +++ b/docs/maintainer-notes.html @@ -266,8 +266,8 @@ any stale remote branches locally by executing:
  • The development mailinglists are debian-kernel@lists.debian.org and initramfs@vger.kernel.org. -Discussion of features, bugs and patches are more than welcome on those -lists.
    • +Discussion of features, bugs and patches are more than welcome on one +of these lists. -- cgit v1.2.3