Using Git to work on the Debian Website
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.
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:
- Register an account on https://salsa.debian.org and enable SSH access by uploading
a public SSH key to your Salsa account. See the Salsa help
pages for more details. Then you can clone the
webwmlrepository using the following command:
git clone email@example.com:webmaster-team/webwml.git
- As an alternative, you can
clone the repository using the HTTPS protocol. Keep in mind that
this will create the local repository, but you won't
be able to directly push changes back this way:
git clone https://salsa.debian.org/webmaster-team/webwml.git
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 firstname.lastname@example.org: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:
git clone --no-checkout email@example.com:webmaster-team/webwml.git
git config core.sparseCheckout true
- Create the file
webwmldirectory 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/
- Finally, you can check out the repo:
git checkout --
Every few days (and definitely before starting some editing work!) you should do a
to retrieve any files from the repository which have changed.
It is strongly recommended to keep your local Git working directory clean
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
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.
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
git clone. Your next steps are:
- Now you can start editing and make changes to the files.
- When you are done, commit your changes to your local repository:
git add path/to/file(s) git commit -m "Your commit message"
- If you have unlimited write access to the remote
webwmlrepository, you may now push your changes directly onto the Salsa repo:
- If you do not have direct write access to the
webwmlrepository, submit your changes with a merge request or contact other developers for help.
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.
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.
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
git log path/to/english/file
If you do a new translation of a file, please use the
It creates a template for your language, including the correct
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
headers when you're working on files manually:
- Make the changes to the original file(s) and commit your changes.
- Update the translations.
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.
- Review the changes (e.g. with
- Commit the translation changes.
Alternatively, you can work with regular expression to make multiple changes across files in one pass:
smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
- Review the changes (e.g. with
- Commit the original file(s).
smart_change.pl origfile1 origfile2(i.e. without the regexp this time). It will now just update the headers in the translated files.
- 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.
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.
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 firstname.lastname@example.org 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.
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.
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.
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
webwml repo via email, please subscribe to the
pseudo package via tracker.debian.org and activate the
there, following these steps (only once):
- Open a web browser and go to https://tracker.debian.org/pkg/www.debian.org.
- Subscribe to the
www.debian.orgpseudo package. (You can authenticate via SSO or register an email and password, if you aren't already using tracker.debian.org for other purposes).
- Go to https://tracker.debian.org/accounts/subscriptions, then to
modify keywords, check
vcs(if it's not checked) and save.
- From now on you will get emails when somebody commits to the
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:
- Log in to your Salsa account and go to the project page.
- Click the bell icon on the top of the project homepage.
- Select the notification level you prefer.