How to Contribute

Mailman is hosted on Gitlab and thus uses git. This page lists the basics to jumpstart contributions. Please refer to git documentation on the internet for detailed explanations of the commands used.

Creating branches

In git it is common to not commit directly into the master branch. Instead changes are committed into separate branches which are then proposed for merging.

The code for creating a new branch is

git checkout -b  <branch_name> <branch_name_to_branch_from>

In case you want to create a branch from the current one, you can ommit the last argument. So to create a new branch from the master branch (Which you probably want to do every time) you use:

git checkout -b my-new-branch master

Adding files

You need to add files before you actually commit. You do this by using the following command:

git add <first_file> <second_file> ...

There also is an interactive mode that can be used to only add parts of files which can be used if you don't want all changes to go into one commit. This is done by calling:

git add -i

Making a commit

Once you have added files you want to commit, it's time to actually commit. The command is:

git commit

This should open up your default editor. Notice that it already contains some text listing all the changes you are about to commit. Every line that starts with a '#' is a comment and ignored.

The actual commit should be split into two sections. The first is just the first line of the commit. The first line should describe the commit in no more than 80 characters. The first line is always followed by an empty line. After that you can provide details that explain the commit. An example of a good commit message is:

Refactor the user model

Changes include:
* Limiting the user name length
* Adding checks for the password

After you entered the message save the file and close it. This will automatically commit.

Push changes

Once you committed your changes in a branch you should push it using:

git push -u <origin> <branch_name>

origin depends on what your remote is called. It's convention to use origin. branch_name is whatever your branch is named.

Create Merge request

Once you pushed your branch it's time to create a merge request. To do this login into Gitlab and go to your fork. You should find the branch overview and click the button to create a merge request from this branch.

Enter a good title and describe your changes in the description. In case your merge request is fixing some issue that is registered on Gitlab you should include this in your description:

Fixes #<issue_number>

There are several different strings you can use to achieve that. An example would be

Fixes #12
closes #11

Doing this will close the issues automatically once the merge request is merged.

Fetching changes from Gitlab

You will want to keep your local repository up to date. Every now and then or whenever you know that there are new commits in the master branch, you will need to update your personal repository as well. This done by fetching and merging. You will first want to fetch changes using:

git fetch <remote_name>

If you followed the setup instructions your own fork is named origin and the original repository upstream. So the command would be:

git fetch upstream

After that make sure you are in the master branch and merge the remote in. The general syntax is:

git checkout <branch_to_update>
git merge <branch_to_get_update_from>

In our case this would be:

git checkout master
git merge upstream/master

You should not have any merge conflicts as you are not supposed to commit anything into the master branch yourself. Once you did this, you can go on to rebase all other branches from the master branch.

Rebasing

If you have a branch but there are merge conflicts with the master branch you have to get your branch up to speed. You can use merge, but rebasing is cleaner. The command is:

git rebase <branch_to_rebase_of>

You will probably be rebasing of the master branch so the command will be:

git rebase master

This will go over every commit you made and ask you to edit files in case of merge conflicts. If you don't have any conflicts the commit will just skip. Please refer to online documentation on how to perform a rebase

Squashing commits or rewriting history

If you have made some commits and want to reorder them, combine them, remove some or even split them git makes this very easy.The command is:

git rebase -i HEAD~<number_of_commits_to_edit>

So if you want to change the last 10 commits you would use:

git rebase -i HEAD~10

This will open up an editor and allow you to perform different actions on each of the commits. Please refer to online documentation on how to actually do the rebase