Help:Toolforge/Version control

This page covers version or source control and code review tools to help users manage files in Toolforge.

What you'll need

Basic understanding of:

Git
Version or source control
Code review

Version control and code review for Toolforge

Code can be edited manually in the Tool Account directory, but we strongly recommend that you use version control or source control and code review tools.

There are several benefits to doing this:

You will have backups and control over any irreplaceable data.
You will be able to track changes to your project over time.
You will have an easier time collaborating with other tool maintainers working on the same Tool Account.
You will be able to build custom container images for your tool.

Git

Git is a popular version control system used by many software developers.

Tool Account collaborators use Git repositories to track changes to files.

For more information about using Git, please see the git documentation.

Setting up repositories

GitLab (recommended)

GitLab is a code hosting, review, and continuous integration platform. The Wikimedia movement maintains a local GitLab server at https://gitlab.wikimedia.org/.

To create a GitLab repository for your Tool Account:

Go to toolsadmin
Find your tool
Click the create new repository button

Repositories created with toolsadmin are collected under the toolforge-repos group.

You can set up your tool to auto-update from GitLab, but consider the risk that auto-updates would impact your live tool if your GitLab repository is ever compromised.

See the GitLab Docs for more documentation.

Gerrit

Gerrit is a code collaboration tool that integrates with Git.

Gerrit is used across Wikimedia technical projects. If you collaborate on tools using Toolforge you will want to be familiar with Gerrit. Gerrit supports code review and git repositories can be accessed via SSH. Learn more about using Gerrit on mediawiki.org.

Request a Gerrit repository for your tool

To use the Wikimedia Cloud VPS code review and version control, you must upload your SSH key to Gerrit and then request a Gerrit repository for your tool.

Log in to https://gerrit.wikimedia.org/ with your Wikimedia developer account username and password.
Add your SSH public key (select “Settings” from the drop-down menu beside your user name in the upper right corner of the screen, and then “SSH Public Keys” from the Settings menu).
Request a Gerrit project for your tool: Gerrit/New repositories

For more information about using Git and Gerrit in general, please see Git/Gerrit.

GitHub, GitLab, Bitbucket, and other Git repositories

Before you start, setup your Git user account. Login to your tool account

$ become mytool

Then you can clone the remote repository:

$ git clone https://github.com/yourGitHubName/yourGitHubRepoName.git

Local Git repository

You can set up a local Git repository to keep backups of versions of your code.

To create a local Git repository:

1. Create an empty Git repository

maintainer@tools-login:~$ git init

2. Add the files you would like to backup. For example:

maintainer@tools-login:~$ git add public_html

3. Commit the added files

git commit -m 'Initial check-in'

Enable simple public HTTP access to local Git repository

If you've set up a local Git repository in your Tool Account directory, you can set up public read access to the repository through HTTP.

This will allow you to clone the Git repository to your own home computer without using another service.

1. Create the www/static/ subdirectory in your tool's home directory:

mkdir ~/www
mkdir ~/www/static/

2. Go to the www/static/ directory. Make a symbolic link to your bare Git repository (the hidden .git subdirectory in the root of your repository):

cd ~/www/static/
ln -s ~/.git yourtool.git

3. Change the directory into the symbolic link. Run the git update-server-info command to generate auxiliary info files needed for the HTTP connectivity:

cd yourtool.git
git update-server-info

4. Enable Git hooks for updating the auxiliary info files every time someone commits, rewrites or pushes to the repository:

ln -s hooks/post-update.sample hooks/post-commit
ln -s hooks/post-update.sample hooks/post-rewrite
ln -s hooks/post-update.sample hooks/post-update
chmod a+x hooks/post-update.sample

You should be able to clone the repository from any remote machine by running the command:

git clone http://tools-static.wmflabs.org/yourtool/yourtool.git

Communication and support

Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation:

Discuss and receive general support

Chat in real time in the IRC channel #wikimedia-cloud ^connect or the bridged Telegram group
Discuss via email after you have subscribed to the cloud@ mailing list

Stay aware of critical changes and plans

Subscribe to the cloud-announce@ mailing list (all messages are also mirrored to the cloud@ list)
Read the News wiki page

Track work tasks and report bugs

Use a subproject of the #Cloud-Services Phabricator project to track confirmed bug reports and feature requests about the Cloud Services infrastructure itself

Read stories and WMCS blog posts

Read the Cloud Services Blog (for the broader Wikimedia movement, see the Wikimedia Technical Blog)