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

The right way to contribute changes to a repository.

## Forking

Nigel Kukard's avatar
Nigel Kukard committed
8
* Log into [LinuxAssist Devlabs GitLab](https://gitlab.devlabs.linuxassist.net)
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
* 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
39
git checkout upstream/master -b your-change-name
40 41 42 43
```

### Committing You Changes

44 45 46 47
The first thing you need to do is review your changes using the following command...
```sh
git diff --staged
```
48

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

51 52 53
#### Adding Hunk-By-Hunk

You can add hunk by hunk, or group of hungs by group of hunks using the following...
54 55

```sh
56
git add --patch <filename>
57 58
```

59 60 61 62 63 64
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...
```sh
65
git reset --patch <filename>
66
```
67 68 69

## Submitting Your Changes

Nigel Kukard's avatar
Nigel Kukard committed
70
Be sure to read the code [Submission Policy](https://gitlab.devlabs.linuxassist.net/allworldit/allworldit/blob/master/Submission%20Policy.md)
71 72 73 74 75 76 77 78 79

### 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
80
git push origin yourbranchname:descriptive-name
81 82 83 84 85 86 87 88
```

### 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
89
* Click "Submit merge request"
90 91 92 93 94 95 96 97 98 99 100 101 102

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

103 104 105 106
To squash all commits since "master", use...

```sh
git rebase -i master
107
```
108 109 110 111

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

```sh
112 113 114
git rebase -i HEAD~X
```

115
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.
116 117 118 119 120 121

### Re-Submitting

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

```
122
git push -f origin yourbranchname:same-descriptive-name
123
```
124 125 126 127 128 129 130 131 132 133 134 135

## 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
136
git push origin yourbranchname:descriptive-name
137 138
```

Nigel Kukard's avatar
Nigel Kukard committed
139
### Bringing Your Branch Up To Date
140

Nigel Kukard's avatar
Nigel Kukard committed
141
Rebase your changes off the main repo. Make sure you are in your branch with your changes committed.
142 143 144

```sh
git fetch upstream
Nigel Kukard's avatar
Nigel Kukard committed
145 146 147 148 149 150
git rebase upstream/master
```

Push your changes...

```sh
151
git push origin yourbranchname:descriptive-name
152
```