Version Control System ====================== The Debian Hamradio Maintainers team has a project on `Salsa `_. You are encouraged to use this for managing git repositories for the source of your team packages. If you do not currently have an account on Salsa or have not requested to be added to the project, you will need to do that before you can use this facility. To request to be added to the project, send an email to the `mailing list `_. In order to be able to push to the repositories on Salsa, you will need to add an SSH key to your Salsa account. Anonymous access to git repositories ------------------------------------ Anonymous access to git repositories is possible at the following URLs: * https://salsa.debian.org/debian-hamradio-team/.git (Preferred for the Vcs-Git field) Anonymous access to a web VCS browser is also available at the following URL: * https://salsa.debian.org/debian-hamradio-team/.git You can also view an `index of all team git repositories `_. Repository layout ----------------- The layout of the Git repository is important as we have QA tools that scan our Git repositories for information. The recommended layout for repositories is described by `DEP-14 `_, which is implemented by the ``git-buildpackage`` tool. Examples of this tool in use are given below. Importing an existing source package ------------------------------------ You will need ``git-buildpackage`` installed on your local machine before following these steps. If your package is not currently tracked with git, you can import the sources from a source package. Begin by logging into Salsa and creating the new repository. To configure the Salsa repository you've created you can use the script at ``_. If you have the source package locally, you can skip this next step. If not, you will need to download the source package from the Debian archives: :: cd /tmp apt-get source Then you need to create a local git repository on your machine and import the source package: :: mkdir cd git init gbp import-dsc --pristine-tar /tmp/*.dsc Finally, in your local git repository, add the remote and push all branches and tags: :: git remote add origin git+ssh://salsa.debian.org/debian-hamradio-team/.git git push origin --all git push origin --tags Please remember to update your ``Vcs-Git`` and ``Vcs-Browser`` fields in ``debian/control`` to match the URLs shown above for anonymous access. Importing an existing git repository ------------------------------------ You will need ``git-buildpackage`` installed on your local machine before following these steps. If you've previously had a git repository elsewhere for your package, you can import it quite easily. Begin by logging into Salsa and creating the new repository. To configure the Salsa repository you've created you can use the script at ``_. Then in your local git repository, add the remote and push all branches and tags: :: git remote remove origin git remote add origin git+ssh://salsa.debian.org/debian-hamradio-team/.git git push origin --all git push origin --tags This repository can now be cloned using git-buildpackage or you can continue to work in your local repository pushing changes to the new origin. Please remember to update your ``Vcs-Git`` and ``Vcs-Browser`` fields in ``debian/control`` to match the URLs shown above for anonymous access. Creating a new git repository for a new package ----------------------------------------------- You will need ``git-buildpackage`` installed on your local machine before following these steps. Begin by logging into Salsa and creating the new repository. On your machine, download the upstream source tarball and keep it somewhere safe. You will need a tarball to import, so if upstream distributes source as a zip or other type of archive, you will need to repack it as a tarball. Create a local git repository on your machine and import the tarball like so: :: mkdir cd git init gbp import-orig --pristine-tar /path/to/upstream/source.tar.gz You'll now find that the upstream source has been imported into your git repository. To configure the Salsa repository you've created you can use the script at ``_. When you are ready to push your changes to Salsa, add the remote and push all branches and tags: :: git remote add origin git+ssh://salsa.debian.org/debian-hamradio-team/.git git push --all git push --tags Updating a package already in the team git ------------------------------------------ You can update an existing Debian package in git to the latest upstream with one of the following commands: :: gbp import-orig --pristine-tar --uscan # will use the watch file to locate # the latest upstream gbp import-orig --pristine-tar --download # will download a tarball # from the URL before # importing gbp import-orig --pristine-tar /path/to/orig.tar.gz # import from local # tarball Testing package builds with git-buildpackage -------------------------------------------- While building your package with git-pbuilder as described below will help you to test building your package on a clean system and check your build dependencies, it can take a long time to install the build dependencies every time. You can build your package in the directory on your development system while debugging build problems. :: gbp buildpackage -us -uc .. note:: The ``-us -uc`` options will be passed to ``dpkg-buildpackage`` and disable the automatic signing of the package. There is no need to sign the built packages when debugging. The .dsc, .changes, .orig.tar.gz, .debian.tar.xz and .deb files will be placed in the parent directory to your git repository. Using git-buildpackage and git-pbuilder for building packages ------------------------------------------------------------- ``git-pbuilder`` builds your package in a chroot which ensures that your package has the correct package dependencies and does not depend on any files outside of the repository. It is included in the ``git-buildpackage`` package. The first time you use git-pbuilder, you'll need to create a local unstable chroot for the builds to be performed in. You will also need to make sure cowbuilder is available on your system. :: sudo apt-get install cowbuilder sudo git-pbuilder create In order to build your package from the git repository, run: :: cd /path/to/repository gbp buildpackage --git-pbuilder Final build and upload ---------------------- If your package is ready for upload, you can update the changelog, perform a final build with the updated changelog, sign your package using debsign and then upload: :: dch -r # this will set the distribution to unstable gbp buildpackage --git-pbuilder --git-tag cd ../ debsign *.changes dput *.changes .. note:: You may choose to do the final build without ``git-pbuilder``, in which case you can omit the ``--git-pbuilder`` argument from the call to ``gbp buildpackage``. The .dsc and .changes files will also be signed during the build so you do not have to use ``debsign`` if you are not using ``git-pbuilder`` for the final build. If you're not a Debian Maintainer or Debian Developer, you will not be able to upload directly into the Debian archives. See the "Publishing your packages" section of the `mentors.debian.org introduction `_ to learn how to upload your package there and then send a mail to the mailing list requesting sponsorship for your package. Backports and updates to stable distributions --------------------------------------------- Backports and updates to stable distributions should be managed in a separate branch in the Git repositories. Backports should be managed in the branch with the name of the stable distribution, e.g. the branch containing backports for the current stable distribution should be named "bullseye". Proposed updates for the stable distributions should be managed in the branch with the name of the stable distribution with "-pu" appended, e.g. the branch containing proposed updates for the current stable distribution should be named "bullseye-pu". In order to use git-buildpackage to build the alternative branch, use the --git-debian-branch argument: :: gbp buildpackage --git-pbuilder --git-debian-branch=bullseye Tracking commit notifications ----------------------------- Commit notifications are displayed in the `#debian-hams `_ IRC channel on irc.debian.org and can also be found on the `debian-hams@lists.debian.org `_ mailing list. Further Reading --------------- For more information on using Git for packaging, see `the Git packages pages on the wiki `_.