Using GitLab.md 4.74 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
## Setting Up Your Git

Setup Git global settings with the below commands...
```sh
git config --global user.name "Your Name"
11
git config --global user.email "your@email"
12 13 14 15 16 17 18
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
* 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
41
git fetch upstream
42 43 44 45
```

## Make Your Changes

46
We first need to branch, add hunks, review and submit.
47 48 49 50 51 52

### Branching

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

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

56
You can now modify the relevant files.
57

58 59
#### Adding Hunk-By-Hunk

60
You can add hunk by hunk, or group of hungs by group of hunks using the following... (filename is optional)
61 62

```sh
63
git add --patch [filename]
64 65
```

66 67
Type ? at the prompt to get further help. The (e)dit option is VERY useful to pull in only changes that are surgical.

68
#### Removing Hunk-By-Hunk (optional)
69 70

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

72
```sh
73
git reset --patch [filename]
74
```
75

76 77 78 79 80 81 82 83 84 85 86 87 88 89
### Committing Your Changes

The first thing you need to do is review your changes using the following command before you commit...
```sh
git diff --staged
```

If you are 100% happy, commit your chagnes using the below, making sure of course all your changes must contain the Signed-Off line...
```sh
git commit
```


### Cherry-picking Your Changes (optional)
90 91 92 93 94 95 96 97 98 99 100

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".



101 102
## Submitting Your Changes

Nigel Kukard's avatar
Nigel Kukard committed
103
Be sure to read the code [Submission Policy](https://gitlab.devlabs.linuxassist.net/allworldit/allworldit/blob/master/Submission%20Policy.md)
104 105 106 107 108 109 110 111

### Push Changes

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

```sh
git fetch upstream
git rebase upstream/master
112
git push origin yourbranchname:descriptive-name
113 114 115 116 117 118 119 120
```

### 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
121
* Click "Submit merge request"
122 123 124 125 126 127 128 129 130 131 132 133 134

## 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.

135 136 137
To squash all commits since "master", use...

```sh
138
git rebase -i upstream/master
139
```
140 141 142 143

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

```sh
144 145 146
git rebase -i HEAD~X
```

147
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.
148 149 150 151 152 153

### Re-Submitting

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

```
154
git push -f origin yourbranchname:same-descriptive-name
155
```
156 157 158 159 160 161 162 163 164 165 166 167

## 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
168
git push origin yourbranchname:descriptive-name
169 170
```

Nigel Kukard's avatar
Nigel Kukard committed
171
### Bringing Your Branch Up To Date
172

Nigel Kukard's avatar
Nigel Kukard committed
173
Rebase your changes off the main repo. Make sure you are in your branch with your changes committed.
174 175 176

```sh
git fetch upstream
Nigel Kukard's avatar
Nigel Kukard committed
177 178 179 180 181 182
git rebase upstream/master
```

Push your changes...

```sh
183
git push origin yourbranchname:descriptive-name
184 185
```