Guidelines/Git-based packaging workflow

From Apertis
Jump to: navigation, search


Git-based packaging workflow

Several OBS Apertis packages are kept in Git source repositories, to be able to maintain and update those packages several recomendations are being adopted:

  • Use of DEP-14 Git layout proposal specification with the following conventions:
    • upstream/{latest,$version} branches with the upstream project code (eg. upstream/2.48.x)
    • apertis/{master,$distro} branches where the upstream branches above get merged with the Apertis packaging (eg. apertis/16.12)
    • apertis/$version tags (eg. apertis/2.48.0-1ubuntu4co1)
  • Packages maintained in Git shall contain a hint file in OBS package folder (MAINTAINED_IN_GIT.txt)
  • Use of git-buildpackage, in particular gbp-pq

Development flow

  • Clone the package Git repository
  • Checkout the apertis/master branch, or the version specific one if you're targeting older releases
  • Import distribution specific patches (debian/patches/) with gbp pq import into a transient branch
  • Hack on the code, adding and amending commits that will be turned into patches using the standard git tools
  • Export the patchset with gbp pq export
  • Add new patches to Git
  • Build the package, build-snapshot should help in this regard
  • Test the package
  • Push changes to Apertis Git following the Contribution process
  • Release changes with the Release process

Automatically closing tasks

See the instructions on how to automatically close tasks in the contribution process.

Generate debian/changelog from the Git log with gbp-dch

gbp-dch is a tool to take your commit messages and turns them in entries for debian/changelog.

With it you can use the following tags in your commit messages:

  • Gbp-Dch: {Full,Short}
    • Short will create a short changelog entry using the short commit message (ie. the first line of the commit message)
    • Full will include the long description in the generated changelog entry
  • Apertis: {$TASK_URL,$TASK_ID}, is translated to (Apertis: Txxxx) in debian/changelog for automated task status tracking
  • Thanks: $SOMEONE if you want to give kudos to someone

Running gbp dch will turn a commit message like:

Update website link to demo images

The website has new path for demo images.

Gbp-Dch: Full
Thanks: Mariano for pointing out the issue

Signed-off-by: Héctor Orón Martínez <>

to the following debian/changelog entry:

  * Update website link to demo images.
    The website has new path for demo images.
    Signed-off-by: Héctor Orón Martínez <>
    Thanks to Mariano for pointing out the issue (Apertis: T12345)

Just make sure your package has the following entries in debian/gbp.conf:

ignore-branch = True
meta-closes = Apertis
meta-closes-bugnum = (?:\d+)

Continuous Integration

Apertis Jenkins instance runs CI jobs for some packages. It sends build results emails to Apertis maintainers mailing list.

CI process shall build Git snapshot packages and commit those to OBS snapshot project, for 16.12, unless Git repository is tagged with a release version therefore, a proper release package shall be built in OBS snapshots project and developer must submit to the relevant OBS distribution project.

In example, if a package has new upstream version, developer tags it according to DEP-14 specification and the package shall be built in OBS snapshot repository, to be able to reach main repositories, the package must be submitted to the final OBS project, for example using the command below:

osc submitrequest apertis:<distro>:snapshots <package> apertis:<distro>:<component>

If you need to release a package from Git repositories, please checkout the following documentation.

Personal tools