Using GitLab.md 4.62 KB
Newer Older
1 2 3 4 5
Contributing to a Repository
============================

The right way to contribute changes to a repository.

6 7 8 9 10 11 12 13 14 15 16 17 18
## Setting Up Your Git

Setup Git global settings with the below commands...
```sh
git config --global user.name "Your Name"
git config --global user.email your@email
git config --global user.signingkey "gpg_fingerprint"

git config --global format.signoff true
git config --global core.whitespace trailing-space,space-before-tab,indent-with-non-tab
git config --global color.ui true
```

19 20
## Forking

Nigel Kukard's avatar
Nigel Kukard committed
21
* Log into [LinuxAssist Devlabs GitLab](https://gitlab.devlabs.linuxassist.net)
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51
* Find the project you're wanting to change, click on the repository
* Top right hand side, click "Fork"

You now have your own copy of the repository.

## Clone Locally

Clone the repository locally...

```sh
git clone ssh://git@gitlab.devlabs.linuxassist.net/yourusername/yourreponame.git
cd yourreponame
git config format.signature true
```

You should probably add the upstream repository too so you can do merges and rebases...

```sh
git remote add upstream ssh://git@gitlab.devlabs.linuxassist.net/upstream/repo.git
```

## Make Your Changes

Make and commit your changes, merge your commits, go mad.

### Branching

For each separate change you going to make you must create a branch...

```sh
52
git checkout upstream/master -b your-change-name
53 54
```

55
### Committing Your Changes
56

57 58 59 60
The first thing you need to do is review your changes using the following command...
```sh
git diff --staged
```
61

62
If you are 100% happy, commit your chagnes as usual, making sure of course all your changes must contain the Signed-Off line.
63

64 65 66
#### Adding Hunk-By-Hunk

You can add hunk by hunk, or group of hungs by group of hunks using the following...
67 68

```sh
69
git add --patch <filename>
70 71
```

72 73 74 75 76
Type ? at the prompt to get further help. The (e)dit option is VERY useful to pull in only changes that are surgical.

#### Removing Hunk-By-Hunk

If you mistakenly git add --patch a wrong hunk or need to ammend it use the following...
77

78
```sh
79
git reset --patch <filename>
80
```
81

82 83 84 85 86 87 88 89 90 91 92 93
#### Cherry-picking Your Changes

Sometimes you may find you have a commit in another branch you wish to submit, this is very easy to do. Git has a cherry-pick command which will fetch the commit and apply it to the branch you're in.

```sh
git cherry-pick de20a8566bf7a996d4bc8bde997fc359560f2b28
```

Remember to review the number of commits in your MR. Typically there should only be 1. See the below section about "Squashing Your Commits".



94 95
## Submitting Your Changes

Nigel Kukard's avatar
Nigel Kukard committed
96
Be sure to read the code [Submission Policy](https://gitlab.devlabs.linuxassist.net/allworldit/allworldit/blob/master/Submission%20Policy.md)
97 98 99 100 101 102 103 104 105

### Push Changes

Make sure your code is based off the main repo and push your branch...

```sh
git fetch upstream
git checkout yourbranchname
git rebase upstream/master
106
git push origin yourbranchname:descriptive-name
107 108 109 110 111 112 113 114
```

### Submit Upstream

Using the web interface you can then create a merge request:
* Click on your repository, click "Create Merge Request"
* Select the repository and branch on the top left and top right
* Type in a description of your changes
115
* Click "Submit merge request"
116 117 118 119 120 121 122 123 124 125 126 127 128

## Post-Review Changes

If you get comments on your code and you need to make changes to the branch merge request, its really easy to do.

### Fixing Your Code

Go through each comment one by one and commit the fixes as required.

### Squashing Your Commits

You do NOT want to submit 20,000 commits, squashing will take all the changes and squash them into 1 commit. Replace X with how many extra comments you made PLUS 1 to include your original commit.

129 130 131
To squash all commits since "master", use...

```sh
132
git rebase -i upstream/master
133
```
134 135 136 137

To squash X number of commits use the following...

```sh
138 139 140
git rebase -i HEAD~X
```

141
In all cases will be presented with a list of commits. Replace `pick` with `s` on all but your original commit. The next step will present you with a commit message with all your commit messages included for edit.
142 143 144 145 146 147

### Re-Submitting

You can now re-submit your changes by forcing a ref update...

```
148
git push -f origin yourbranchname:same-descriptive-name
149
```
150 151 152 153 154 155 156 157 158 159 160 161

## Further Changes

There are multiple ways to contribute further changes.

### Simply Branch Main Repo (easy way)

Branch the original repo and apply your changes to it.

```sh
git fetch upstream
git checkout upstream/master -b yourbranchname
162
git push origin yourbranchname:descriptive-name
163 164
```

Nigel Kukard's avatar
Nigel Kukard committed
165
### Bringing Your Branch Up To Date
166

Nigel Kukard's avatar
Nigel Kukard committed
167
Rebase your changes off the main repo. Make sure you are in your branch with your changes committed.
168 169 170

```sh
git fetch upstream
Nigel Kukard's avatar
Nigel Kukard committed
171 172 173 174 175 176
git rebase upstream/master
```

Push your changes...

```sh
177
git push origin yourbranchname:descriptive-name
178 179
```