<> == Packaging guidelines == * Packages should use Git, as mentioned above. * Upstream sources should be obtainable via {{{debian/rules get-orig-source}}} * Packages are build from tarballs that upstream provides at {{{http://pub.mate-desktop.org/releases/}}} * The ''master'' branch should only contain the {{{debian/}}} directory. * This means no direct changes to the source can be made in Git. Instead a patch manager ({{{quilt}}}) must be used for patch management. * The maintainer field should be set to {{{MATE Packaging Team }}} * The Git repository should be hosted on Alioth, under the pkg-mate project. It should forward commit messages to {{{pkg-mate-commits@lists.alioth.debian.org}}} and ''package''{{{_cvs@packages.qa.debian.org}}} * You can use the {{{./setup-git-repository}}} script in {{{/git/pkg-mate}}} (on host {{{git.debian.org}}}) to create the bare repository with commit messages enabled. The repository should be named as the source package name for the message forwarding to work (e.g. the repository for source package mate-terminal is named mate-terminal.git).{{{ $ ssh -l git.deban.org $ cd /git/pkg-mate $ ./setup-git-repository }}} * The control file should use the Vcs-Git and Vcs-Browser tags. == Workflow guidelines == * '''One change per commit'''. This is very important, it eases review, cherry picking, bisecting (and thus debugging) and backporting. * Do not commit {{{debian/changelog}}} along with the changes. This practice makes cherry-picking and backporting changes unnecessarily hard. The changelog is generated with [[DebianMan:1/git-dch|git-dch(1)]] at the time of upload. * The commit message should have a short (<78 characters) summary of the change followed by a newline. After that, you can elaborate on the change. The summary is treated specially by various tools like [[DebianMan:1/git-dch|git-dch(1)]], or the commitdiff mailer. * When releasing a package, the changelog gets created via{{{ $ git dch --auto }}} This command generates a changelog stanza from the Git commits for the current package version. Thus, choose your Git commit messages well--as if they were entries in `debian/changelog`. They actually are!!! * Then simply run {{{dch -r}}} which will mark the package from UNRELEASED to released (normally {{{unstable}}}). * Now commit the generated changelog stanza (editing and fine-tuning it is allowed) to Git and (e.g. for Debian release 1.6.1-1 of the mate-common package) use a commit message like{{{ git commit -a -m "upload to unstable (debian/1.6.1-1)" }}} * Build (e.g. with {{{sbuild}}}) and upload the package to Debian unstable.{{{ $ cd $ debuild -uc -us -S -Zxz $ cd .. $ sbuild -sAd unstable .dsc }}} * If you have not used {{{lintian}}} for checking the package integrity, then it is really time for it now:{{{ $ lintian -iIE --pedantic --show-overrides --color auto _.changes }}} * Only if {{{lintian}}} is considerably silent and content with your package effort, the package is suitable for an upload to Debian unstable. Do not upload a package that {{{lintian}}} still reports errors for. * Now, sign the package (using {{{debsign}}} and (if you are a DD or a DM) upload the package (using e.g. {{{dput}}}):{{{ $ debsign _.changes $ dput _.changes }}} * For uploads to NEW: be patient and wait for the FTP masters to accept the uploaded package... (if they reject it, mark the package as UNRELEASED again and fix what the FTP team requests from you) * Tags should be created (and signed) by the uploading DD, in the case of the debian/* tags in the master branch, and by the person importing the upstream sources in the case of upstream tags:{{{ git tag -s debian/1.6.1-1 -m "Debian release 1.6.1-1" }}} * After each upload, the first commit should be creating a new changelog entry, to ease testing of unreleased packages. == Documentation == * [[http://wiki.debian.org/Alioth/Git | Using git on Alioth]] == Working on existing packages with Git for newbies == * As a very basic introduction, first read PackagingWithGit. * locate the packaging branch on the [[ http://git.debian.org/?s=pkg-mate | pkg-mate Git index ]] * Note the metadata just above the shortlog, it contains 2 URLs, one of them starting with `git://` * then [[ http://www.kernel.org/pub/software/scm/git/docs/git-clone.html | git-clone(1) ]] to get a copy of the repository. E.g. {{{ git clone git://git.debian.org/pkg-mate/.git }}} * get the upstream source tarball belonging to that package:{{{ $ debian/rules get-orig-source }}} * do changes to that branch, build the package:{{{ $ debuild -uc -us -Zxz }}} ... and test your changes. Commit early and often! Do regular pushes to the origin Git repos on Alioth.{{{ $ git push origin }}} * If someone else has committed while you are working on the branch, you need to integrate his/her changes. For this you have 2 options: * if your local changes are rather minor and clean, rebase when using [[ http://www.kernel.org/pub/software/scm/git/docs/git-pull.html | git-pull(1) ]]: {{{ $ git pull --rebase origin }}} * only if you rather don't want to break your history because you think that your changes are rather large and are likely to interfere with the other changes, better merge them with: {{{ $ git pull origin }}} * In case you want to cleanup your local commits before pushing, use [[ http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html | git-rebase(1) ]]: {{{ $ git rebase -i origin/master }}} You will be presented a textfile where you can specify what of your local commits you want to modify, drop or squish (merge with the previous one). You can also improve your commit message here. Make sure that you don't rewrite already published commits. * In order to get comments on your (preferably cleaned up) commits, use [[ http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html | git-format-patch(1) ]] to generate patches of your commits and email them to the mailing list. Any committer can do this while preserving attribution. * None of the steps above require membership in the pkg-multimedia alioth group. All of that can be done totally anonymously! === Uploading new upstream version to existing repository === * Updating a git branch {{{ $ git checkout master $ git pull }}} * resolve merge conflicts, review your changes e.g. with `gitk` * pushing new revisions {{{ $ git push origin master --tags --dry-run }}} * if happy, remove the --dry-run parameter *'''Assumptions in all cases''' * in the source tree * the remote 'alioth' is setup properly ---- CategoryGit