Using Git to work on the Debian Website

Working on the Git Repository

Let's jump right into it — in this section you will learn how to create a local copy of the main repository, how to keep that repo up-to-date, and how to submit your work. We'll also explain how to work on translations.

Get a local Copy

First, install Git. Next, configure Git and enter your name and email address. If you're a new Git user, then it's probably a good idea to read the general Git documentation first.

Your next step is to clone the repository (in other words: make a local copy of it). There are two ways to do this:

Tip: Cloning the entire webwml repository requires downloading about 1.3 GB of data which might be too much if you're on a slow or unstable internet connection. Therefore, it's possible to define a minimum depth for a smaller initial download: 

  git clone [email protected]:webmaster-team/webwml.git --depth 1

After obtaining a usable (shallow) repository, you can deepen the local 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

You can also check out only a subset of the pages:

  1. git clone --no-checkout [email protected]:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Create the file .git/info/sparse-checkout inside the webwml directory to define the content you want to check out. For example, if you only want to retrieve the base files, English, Catalan, and Spanish translations, the file looks like this: 
          /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
  5. Finally, you can check out the repo: git checkout --

Submit local Changes

Keep your local Repo up-to-date

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.

It is strongly recommended to keep your local Git working directory clean before performing git pull and starting to edit some files. If you have uncommitted changes or local commits that are not present in the remote repository on the current branch, running git pull will automatically create merge commits or even fail due to conflicts. Please consider keeping your unfinished work in another branch or using commands like git stash.

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.

Example: editing some Files

Let's look at a more practical example and a typical editing session. We're assuming that you have obtained a local copy of the repo using git clone. Your next steps are:

  1. git pull
  2. Now you can start editing and make changes to the files.
  3. When you are done, commit your changes to your local repository: 
        git add path/to/file(s)
    git commit -m "Your commit message"
  4. If you have unlimited write access to the remote webwml repository, you may now push your changes directly onto the Salsa repo: git push
  5. If you do not have direct write access to the webwml repository, submit your changes with a merge request or contact other developers for help.

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/TLS, 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

Translations should always be kept to be up-to-date with its corresponding English file. The translation-check header in translation files is used to track which version of English file the current translation was based on. 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 identify the hash with the following command:

  git log path/to/english/file

If you do a new translation of a file, please use the copypage.pl script. It creates 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.

This is how to use smart_change.pl and how 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 your changes.
  2. Update the translations.
  3. Run smart_change.pl -c COMMIT_HASH (use the commit hash of the changes in the original file(s)). 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.

Alternatively, you can work with 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 the headers in the translated files.
  5. Finally, commit the translation changes.

Admittedly, this requires a bit more effort than the first example as it involves two commits, but unavoidable due to the way Git hashes work.

Write Access to the Git Repository

The source code of the Debian website is managed with Git and located at https://salsa.debian.org/webmaster-team/webwml. By default, guests are not allowed to push commits to the source code repository. If you want to contribute to the Debian website, you need some kind of permission to gain write access to the repository.

Unlimited Write Access

If you need unlimited write access to the repository, e.g. if you're about to become a frequent contributor, please request write access 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 an email to [email protected] and introduce yourself before requesting unlimited write access. Would you be so kind and tell us more about yourself, for example, which part of the website you plan to work on, which languages you speak, and also if there is another Debian team member who can vouch for you.

Merge Requests

It's not necessary to get unlimited write access to the repository — you can always submit a merge request and let other developers review and accept your work. Please follow the standard procedure for merge requests provided by the Salsa GitLab platform via its web interface and read the following two documents:

Please note that merge requests aren't monitored by all website developers. Therefore, it might take some time before you receive some feedback. If you wonder whether your contribution will get accepted or not, please send a email to the debian-www mailing list and ask for a review.

Receiving Notifications

If you're working on the Debian website, you probably want know what's going on in the webwml repository. There are two ways to stay in the loop: commit notifications and merge request notifications.

Receiving Commit 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 about commits in the webwml repo via email, please subscribe to the www.debian.org pseudo package via tracker.debian.org and activate the vcs keyword there, following these steps (only once):

  1. Open a web browser and go to https://tracker.debian.org/pkg/www.debian.org.
  2. Subscribe to the www.debian.org pseudo package. (You can authenticate via SSO or register an email and password, if you aren't already using tracker.debian.org for other purposes).
  3. Go to https://tracker.debian.org/accounts/subscriptions, then to modify keywords, check vcs (if it's not checked) and save.
  4. From now on you will get emails when somebody commits to the webwml repo.

Receiving Merge Request Notifications

If you wish to receive notification emails whenever there are new merge requests submitted on the webwml repository in Salsa, you may configure your notification settings on the web interface, following these steps:

  1. Log in to your Salsa account and go to the project page.
  2. Click the bell icon on the top of the project homepage.
  3. Select the notification level you prefer.