path: root/english/devel/website/using_git.wml

#use wml::debian::template title="Using git to manipulate website source code"

<h2>Introduction</h2>

<p>Git is a <a href="https://en.wikipedia.org/wiki/Version_control">version
control system</a> 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.</p>

<p>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 <code>rebase</code> your new modifications on top of the latest
commit as needed.
</p>

<h3><a name="write-access">Git repository write access</a></h3>

<p>
The whole Debian website source code is managed under Git. It is located
at <url https://salsa.debian.org/webmaster-team/webwml/>. By default,
guests are not allowed to push commits onto the source code repository.
You will need some kind of permission to gain write access to the
repository.
</p>

<h4><a name="write-access-unlimited">Unlimited write access</a></h4>
<p>
If you need unlimited write access to the repository (e.g., You are about to
become a frequent contributor), please consider requesting write access via
the <url https://salsa.debian.org/webmaster-team/webwml/> web interface after
logging in to Debian's Salsa platform.
</p>

<p>
If you are new to Debian's website development and have no previous experience,
please also send a mail to <a href="mailto:debian-www@lists.debian.org">
debian-www@lists.debian.org</a> with your self introduction before requesting
unlimited write access. Please provide with 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.
</p>

<h4><a name="write-access-via-merge-request">Write into repository via Merge Requests</a></h4>
<p>
If you do not intend to get unlimited write access to the repository or
is unable to do so, you can always submit a Merge Request and let other
developers to review and accept your work. Please submit Merge Requests
using the standard procedure as provided by the Salsa GitLab platform via
its web interface (read
<a href="https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html">Project forking workflow</a>
and
<a href="https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#when-you-work-in-a-fork">When you work in a fork</a>
for details).
</p>

<p>
The Merge Requests are not monitored by all website developers thus it may
not always be processed in time. If you are not sure whether your contribution
would be accepted, please send a email to the
<a href="https://lists.debian.org/debian-www/">debian-www</a>
mailing list and request for a review.
</p>

<h2><a name="work-on-repository">Working on the repository</a></h2>

<h3><a name="get-local-repo-copy">Get a local copy of the repository</a></h3>

<p>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.</p>

<p>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 <a
href="https://salsa.debian.org/help/ssh/README.md">salsa help
pages</a> for more details on how to do that. Then you can clone the
webwml repository using the following command:</p>

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

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

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

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

<p>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:</p>

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

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

<pre>
  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
</pre>

<h4><a name="partial-content-checkout">Partial content checkout</a></h4>

<p>You can create a checkout for only a subset of the pages like this:</p>

<pre>
   $ 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 --
</pre>

<h3><a name="submit-changes">Submitting local changes</a></h3>

<h4><a name="keep-local-repo-up-to-date">Keep your local repo up-to-date</a></h4>

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

<pre>
   git pull
</pre>

<p>to retrieve any files from the repository which have changed.</p>

<p>
It is strongly recommended to keep your local git working directory clean
before performing "git pull" and following editing work. If you have
uncommitted changes or local commits that are not present in the remote
repository on the current branch, doing "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".
</p>

<p>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.</p>

<h4><a name="example-edit-english-file">Example on editing English files</a></h4>

<p>
An example on how to edit English files within the website source code
repository is provided here. After obtaining a local copy of the repo
using "git clone" and before starting the editing work, run the following
command:
</p>

<pre>
   $ git pull
</pre>

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

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

<p>If you have unlimited write access to the remote webwml repository, you
may now push your changes directly onto the Salsa repo:</p>

<pre>
   $ git push
</pre>

<p>If you do not have direct write access to the webwml repository, please
consider submitting your changes using the Merge Request function as provided
by Salsa GitLab platform or asking other developers for help.
</p>

<p>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.</p>

### FIXME: Is the following still true? holgerw
### FIXME: Seems not true anymore. Needs fixup. -- byang
<h4><a name="closing-debian-bug-in-git-commits">Closing Debian bugs in git commits</a></h4>

<p>
If you include <code>Closes: #</code><var>nnnnnn</var> in your commit log
entry, then bug number <code>#</code><var>nnnnnn</var> will be closed
automatically when you push your changes. The precise form of this is the same as
<a href="$(DOC)/debian-policy/ch-source.html#id24">in Debian policy</a>.</p>

<h4><a name="links-using-http-https">Linking using HTTP/HTTPS</a></h4>

<p>Many Debian websites support SSL/TLS, so please use HTTPS links where
possible and sensible. <strong>However</strong>, 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.</p>

<p>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.</p>

<h3><a name="translation-work">Working on translations</a></h3>

<p>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 find that hash
with</p>

<pre>
$ git log path/to/english/file
</pre>

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

<h4><a name="translation-smart-change">Translation changes with smart_change.pl</a></h4>

<p><code>smart_change.pl</code> 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.</p>

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

<ol>
  <li>Make the changes to the original file(s), and commit</li>
  <li>Update translations</li>
  <li>Run smart_change.pl - it will pick up the changes and update
    headers in the translated files</li>
  <li>Review the changes (e.g. with "git diff")</li>
  <li>Commit the translation changes</li>
</ol>

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

<ol>
  <li>Run <code>smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...</code></li>
  <li>Review the changes (e.g. with <code>git diff</code>)
  <li>Commit the original file(s)</li>
  <li>Run <code>smart_change.pl origfile1 origfile2</code>
    (i.e. <strong>without the regexp</strong> this time);it will now
    just update headers in the translated files</li>
  <li>Finally, commit the translation changes</li>
</ol>

<p>This is more involved than the previous one (needing two commits), but
unavoidable due to the way git commit hashes work.</p>

<h2><a name="notifications">Getting notifications</a></h2>

<h3><a name="commit-notifications">Receiving commit notifications</a></h3>

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

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

<ul>
  <li>Open a web browser and go to <url https://tracker.debian.org/pkg/www.debian.org></li>
  <li>Subscribe to the <q>www.debian.org</q> pseudopackage. (You can authenticate
      via SSO or register an email and password, if you were not using
      tracker.debian.org already for other purposes).</li>
  <li>Go to <url https://tracker.debian.org/accounts/subscriptions/>, then to <q>modify
      keywords</q>, check <q>vcs</q> (if it's not checked) and save.</li>
  <li>From now on you will get e-mails when somebody commits to the
      webwml repo. We will add the other webmaster-team repositories soon.</li>
</ul>

<h3><a name="merge-request-notifications">Receiving Merge Request notifications</a></h3>

<p>
If you wish to receive notification emails whenever there are new Merge
Requests submitted on the webwml repository web interface on Salsa GitLab
platform, you may configure your notification settings for the webwml
repository on the web interface, following these steps:
</p>

<ul>
  <li>Log in to your Salsa account and go to the project page;</li>
  <li>Click the bell icon on the top of the project homepage;</li>
  <li>Select the notification level you prefer.</li>
</ul>