Using GitLab.md 4.31 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
git config --global user.signingkey "gpg_fingerprint"

git config --global format.signoff true
15
git config --global core.whitespace trailing-space,space-before-tab
16 17 18
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
* 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

29
Clone the origin repository...
30 31

```sh
32
git clone ssh://git@gitlab.devlabs.linuxassist.net/upstream/repo.git
33 34 35
git config format.signature true
```

36
Add your repository remote...
37 38

```sh
39
git remote add $USER ssh://git@gitlab.devlabs.linuxassist.net/yourusername/repo.git
40 41 42 43
```

## Make Your Changes

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

### Branching

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

```sh
51 52
git fetch origin
git checkout origin/master -b your-change-name
53 54
```

55 56
Check the commit log and try use branch names that relate to software modules or components.

57
You can now modify the relevant files.
58

59 60
#### Adding Hunk-By-Hunk

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

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

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

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

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

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

77 78 79 80 81 82 83 84 85
### 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
86
git commit --signoff
87 88 89 90
```


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

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



102 103
## Submitting Your Changes

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

### Push Changes

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

```sh
111 112 113
git fetch origin
git rebase origin/master
git push $USER -f
114 115
```

116 117
We use the -f option for force overwriting of your branch in your forked repository.

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

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

138 139
You can also re-order commits in order to squash similar commits together.

140 141 142
To squash all commits since "master", use...

```sh
143 144
git fetch origin
git rebase -i origin/master
145
```
146 147 148 149

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

```sh
150 151 152
git rebase -i HEAD~X
```

153
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.
154

155
### Re-Pushing
156

157
You can now re-push your changes by forcing a ref update...
158 159

```
160 161 162
git fetch origin
git rebase origin/master
git push $USER -f
163 164
```