Differences between revisions 7 and 8
Revision 7 as of 2016-03-09 23:10:04
Size: 8039
Editor: SimonHanna
Comment: Add note to merge requests
Revision 8 as of 2016-03-10 01:31:48
Size: 8357
Editor: barry
Comment:
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:
Mailman is hosted on Gitlab and thus uses [[https://git-scm.com/|git]]. This page lists the basics to jumpstart contributions. Please refer to git documentation on the internet for detailed explanations of the commands used. This should cover the basics you need to contribute. If you think anything could be improved or added please do so, or contact [[http://wiki.list.org/SimonHanna|me]] to do so. In case you have any questions please try to find the answers online. You should be able to find enough using google, otherwise ask on the irc channel. Mailman is [[https://gitlab.com/mailman/mailman|hosted on GitLab]] and thus uses [[https://git-scm.com/|git]]. This page lists the basics to jumpstart contributions. Please refer to git documentation on the internet for detailed explanations of the commands used. This should cover the basics you need to contribute. If you think anything could be improved or added please do so, or contact [[http://wiki.list.org/SimonHanna|me]] to do so. In case you have any questions please try to find the answers online. You should be able to find enough using Google, otherwise ask on the IRC channel (#mailman on freenode).
Line 16: Line 16:
mkdir -p ~/dev/mailman $ mkdir -p ~/dev/mailman
Line 19: Line 19:
Make sure you have a ssh-key, if you don't just run the following command and press enter until you're back to the normal shell Make sure you have a ssh-key, if you don't just run the following command and press enter until you're back to the normal shell:
Line 21: Line 21:
ssh-keygen $ ssh-keygen
Line 24: Line 24:
Before you do anything you will need to create your own fork of the project. If you don't have an account at [[https://gitlab.com|gitlab]] now is the time to create one.
If you haven't uploaded your public ssh-key, do so now. Visit the [[https://gitlab.com/profile/keys|page]] to add ssh-keys and paste in your public key. (It should be ~/.ssh/id_rsa.pub)
Before you do anything you will need to create your own fork of the project. If you don't have an account at [[https://gitlab.com|GitLab]] now is the time to create one.
If you haven't uploaded your public ssh-key, do so now. Visit your [[https://gitlab.com/profile/keys|profile page]] to add ssh-keys and paste in your public key. (It should be ~/.ssh/id_rsa.pub)
Line 27: Line 27:
Visit [[https://gitlab.com/mailman/mailman|mailman's page]] on gitlab and create a fork by pressing the fork button. In case you already have a fork, this will just take you to your own fork. Visit [[https://gitlab.com/mailman/mailman|Mailman's page]] on gitlab and create a fork by pressing the fork button. In case you already have a fork, this will just take you to your own fork.
Line 29: Line 29:
Once you are in your fork copy the ssh url of your fork. This should be something like: From your fork's !GitLab page, copy the ssh url, which should be something like:
Line 31: Line 31:
git@gitlab.com:username/mailman.git git@gitlab.com:<username>/mailman.git
Line 34: Line 34:
now it's time to clone your fork. Be sure to replace the url with your own. Now it's time to clone your fork. Be sure to replace the url with your own.
Line 37: Line 37:
cd ~/dev/mailman
git clone git@gitlab.com:username/mailman.git
$ cd ~/dev/mailman
$ git clone git@gitlab.com:<username>/mailman.git
Line 41: Line 41:
This will create a remote called origin that points to your fork. You will want to add another remote to be able to fetch changes that others do. Note that this time we will be using the url of the mailman project itself and not your forks url This will create a remote called origin that points to your fork. You will want to add another remote to be able to fetch changes that others do. Note that this time we will be using the url of the Mailman project itself, and not your fork's url:
Line 43: Line 43:
cd ~/dev/mailman/mailman
git remote add upstream git@gitlab.com:mailman/mailman.git
$ cd ~/dev/mailman/mailman
$ git remote add upstream git@gitlab.com:mailman/mailman.git
Line 47: Line 47:
Now you are up and running. You can clone all other projects into ~/dev/mailman/<project_name> the same way as above. Now you are up and running. You can clone all other projects into {{{~/dev/mailman/<project_name>}}} the same way as above.
Line 52: Line 52:
 1. Unless it's a really trivial change create an issue on gitlab  1. Unless it's a really trivial change, *always* [[https://gitlab.com/mailman/mailman/issues|create an issue]] on !GitLab first
Line 56: Line 56:
 5. Create Merge request  5. Create a merge request
Line 60: Line 60:
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. 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.
Line 64: Line 64:
git checkout -b <branch_name> <branch_name_to_branch_from> $ git checkout -b <branch_name> <branch_name_to_branch_from>
Line 67: Line 67:
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: In case you want to create a branch from the current one, you can omit the last argument. So to create a new branch from the master branch (Which you probably want to do every time you work on a new issue) you use:
Line 69: Line 69:
git checkout -b my-new-branch master $ git checkout -b my-new-branch master
Line 74: Line 74:
git checkout -b my-new-branch $ git checkout -b my-new-branch
Line 81: Line 81:
git add <first_file> <second_file> ... $ git add <first_file> <second_file> ...
Line 86: Line 86:
git add -i $ git add -i
Line 93: Line 93:
git commit $ git commit
Line 113: Line 113:
git push -u <origin> <branch_name> $ git push -u <origin> <branch_name>
Line 116: Line 116:
origin depends on what your remote is called. It's convention to use origin. branch_name is whatever your branch is named. <origin> depends on what your remote is called. It's convention to use {{{origin}}}. <branch_name> is whatever your branch is named.
Line 121: Line 121:
Please keep using the same merge request and don't open new ones when you change your code. In case you change previous commits you can always force push to the remote branch. Keeping your changes in one merge request makes it easier to track progress and see how the code is evolving While working on the same issue, please keep using the same merge request. Only open a new branch/merge request for a new issue. In case you change previous commits you can always force push to the remote branch. (barry: is this really a good idea?) Keeping your changes in one merge request makes it easier to track progress and see how the code is evolving.
Line 124: Line 124:
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. 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.
Line 126: Line 126:
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: Enter a good title and describe your changes in the description. If your merge request is fixing some issue that is registered on !GitLab you should include this in your description:
Line 132: Line 132:
There are several different strings you can use to achieve that. An example would be There are several different strings you can use to achieve that, for example:
Line 140: Line 140:
== Fetching changes from Gitlab == == Fetching changes from GitLab ==
Line 142: Line 142:
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: 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:
Line 144: Line 144:
git fetch <remote_name> $ git fetch <remote_name>
Line 146: Line 146:
If you followed the setup instructions your own fork is named origin and the original repository upstream. So the command would be: If you followed the setup instructions, your own fork is named {{{origin}}} and the original repository is named {{{upstream}}}. So the command would be:
Line 148: Line 148:
git fetch upstream $ git fetch upstream
Line 153: Line 153:
git checkout <branch_to_update>
git merge <branch_to_get_update_from>
$ git checkout <branch_to_update>
$ git merge <branch_to_get_update_from>
Line 159: Line 159:
git checkout master
git merge upstream/master
$ git checkout master
$ git merge upstream/master
Line 170: Line 170:
git rebase <branch_to_rebase_of> $ git rebase <branch_to_rebase_of>
Line 173: Line 173:
You will probably be rebasing of the master branch so the command will be: You will probably be rebasing off the master branch so the command will be:
Line 175: Line 175:
git rebase master $ git rebase master
Line 178: Line 178:
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 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 work. Please refer to online documentation on how to perform a rebase.
Line 184: Line 184:
git rebase -i HEAD~<number_of_commits_to_edit> $ git rebase -i HEAD~<number_of_commits_to_edit>
Line 189: Line 189:
git rebase -i HEAD~10 $ git rebase -i HEAD~10
Line 192: Line 192:
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 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.

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. This should cover the basics you need to contribute. If you think anything could be improved or added please do so, or contact me to do so. In case you have any questions please try to find the answers online. You should be able to find enough using Google, otherwise ask on the IRC channel (#mailman on freenode).

Initializing repositories

This section will guide you through the process of initializing your forks and local repositories. Please note that the rest of the document will assume the locations and names used here. These can of course be adapted if you want something else.

The process will be demonstrated for mailman-core. Setting up the other projects is mainly just swapping out names.

Setting up your pc

Create a directory that will hold all the projects.

$ mkdir -p ~/dev/mailman

Make sure you have a ssh-key, if you don't just run the following command and press enter until you're back to the normal shell:

$ ssh-keygen

Before you do anything you will need to create your own fork of the project. If you don't have an account at GitLab now is the time to create one. If you haven't uploaded your public ssh-key, do so now. Visit your profile page to add ssh-keys and paste in your public key. (It should be ~/.ssh/id_rsa.pub)

Visit Mailman's page on gitlab and create a fork by pressing the fork button. In case you already have a fork, this will just take you to your own fork.

From your fork's GitLab page, copy the ssh url, which should be something like:

git@gitlab.com:<username>/mailman.git

Now it's time to clone your fork. Be sure to replace the url with your own.

$ cd ~/dev/mailman
$ git clone git@gitlab.com:<username>/mailman.git

This will create a remote called origin that points to your fork. You will want to add another remote to be able to fetch changes that others do. Note that this time we will be using the url of the Mailman project itself, and not your fork's url:

$ cd ~/dev/mailman/mailman
$ git remote add upstream git@gitlab.com:mailman/mailman.git

Now you are up and running. You can clone all other projects into ~/dev/mailman/<project_name> the same way as above.

Development Workflow

  1. Unless it's a really trivial change, *always* create an issue on GitLab first

  2. Create a new branch for this issue
  3. Start coding
  4. Push the branch
  5. Create a merge request

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 omit the last argument. So to create a new branch from the master branch (Which you probably want to do every time you work on a new issue) you use:

$ git checkout -b my-new-branch master

If you are in the master branch you can use

$ git checkout -b my-new-branch

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

While working on the same issue, please keep using the same merge request. Only open a new branch/merge request for a new issue. In case you change previous commits you can always force push to the remote branch. (barry: is this really a good idea?) Keeping your changes in one merge request makes it easier to track progress and see how the code is evolving.

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. If 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, for example:

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 is named 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 off 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 work. 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.

MailmanWiki: DEV/HowToContributeGit (last edited 2021-09-13 22:52:56 by maxking)