Using git to manipulate website source code

Git is a version control system that helps to manage having multiple people work on the same material simultaneously. Every user can hold a local copy of a main repository. The local copies can be on the same machine, or across the world. Users can then modify the local copy as they wish and when the modified material is ready, commit the changes and push them back to the main repository.

Git will not let you push a commit directly if the remote repository has any newer commits (modifications) than your local copy on the same branch. In such case where conflict takes place, please fetch and update your local copy first and rebase your new modifications on top of the latest commit as needed.

git write access

If you need write access to the repository, please request it via the https://salsa.debian.org/webmaster-team/webwml web interface after logging in to Debian's Salsa platform. If you are new to Debian's website development and have no previous experience, please also send a mail to debian-www@lists.debian.org with your self introduction. Please write something useful in your introduction, like which language or which part of the website you plan to work on, and who would vouch for you.

Working on the repository

Clone a local copy of the repository

First, you need to install git to work with the repository. Next, configure your user and e-mail details on your computer (please refer to general git documentation to learn how to do this). Then, you can clone the repository (in other words, make a local copy of it) in one of two ways.

The recommended way to work on webwml is to first register an account on salsa.debian.org and enable git SSH access by uploading an SSH public key into your salsa account. See the salsa help pages for more details on how to do that. Then you can clone the webwml repository using the following command:

   git clone git@salsa.debian.org:webmaster-team/webwml.git

If you don't have a salsa account, an alternative method is to clone the repository using the HTTPS protocol:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

This will give you the same repository copy locally, but you will not be able to directly push changes back directly this way.

Cloning the whole webwml repository will require downloading about 500MB of data, thus it may be difficult for those with slow or unstable Internet connections. You may try shallow cloning with a minimum depth first for a smaller initial download:

  git clone git@salsa.debian.org:webmaster-team/webwml.git --depth 1

After obtaining a usable (shallow) repository, you can deepen the local shallow copy and eventually convert it to a full local repository:

  git fetch --deepen=1000 # deepen the repo for another 1000 commits
  git fetch --unshallow   # fetch all missing commits, convert the repo to a complete one

Partial content checkout

You can create a checkout for only a subset of the pages like this:

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   In webwml: Create the file .git/info/sparse-checkout with content like this
   (if you only want the base files, English, Catalan and Spanish translations):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   Then:
   $ git checkout --

Submitting local changes

Every few days (and definitely before starting some editing work!) you should do a

   git pull

to retrieve any files from the repository which have changed.

Note: git is a distributed (not centralised) version control system. This means that when you commit changes they will only be stored in your local repository. To share them with others, you will also need to push your changes to the central repository on salsa.

So editing an English file will work like this:

   $ git pull

Now make changes to files. When you are done, commit your changes to your local repository using:

   $ git add path/to/file(s)
   $ git commit -m "Your commit message"

Then, push your changes to the Salsa repo:

   $ git push

That's a very basic summary of how to use git to manipulate the Debian website's source code. For more information on git, please read git's documentation.

Closing Debian bugs in git commits

If you include Closes: #nnnnnn in your commit log entry, then bug number #nnnnnn will be closed automatically when you push your changes. The precise form of this is the same as in Debian policy.

Linking using HTTP/HTTPS

Many Debian websites support SSL, so please use HTTPS links where possible and sensible. However, some Debian/DebConf/SPI/etc websites either don't have have HTTPS support or only use the SPI CA (and not an SSL CA trusted by all browsers). To avoid causing error messages for non-Debian users, please do not link to such sites using HTTPS.

The git repository will reject commits containing plain HTTP links for Debian websites that support HTTPS or containing HTTPS links for the Debian/DebConf/SPI websites that are known to either not support HTTPS or use certificates signed only by SPI.

Working on translations

If you change translated files, you need to update the translation-check header to match the git commit hash of the corresponding change in the English file. You can find that hash with

$ git log path/to/english/file

If you do a new translation of a file, please use the copypage.pl script and it will create a template for your language, including the correct translation header.

Translation changes with smart_change.pl

smart_change.pl is a script designed to make it easier to update original files and their translations together. There are two ways to use it, depending on what changes you are making.

To use smart_change to just update the translation-check headers when you're working on files manually:

  1. Make the changes to the original file(s), and commit
  2. Update translations
  3. Run smart_change.pl - it will pick up the changes and update headers in the translated files
  4. Review the changes (e.g. with "git diff")
  5. Commit the translation changes

Or, if you're using smart_change with a regular expression to make multiple changes across files in one pass:

  1. Run smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
  2. Review the changes (e.g. with git diff)
  3. Commit the original file(s)
  4. Run smart_change.pl origfile1 origfile2 (i.e. without the regexp this time);it will now just update headers in the translated files
  5. Finally, commit the translation changes

This is more involved than previously (needing two commits), but unavoidable due to the way git commit hashes work

Getting notifications

We have configured the webwml project in Salsa so that commits are shown in the IRC channel #debian-www.

If you want to receive notifications via e-mail when there are commits in the webwml repo, please subscribe to the www.debian.org pseudopackage via tracker.debian.org and activate the vcs keyword there, following these steps (only once):