Using GitLab.md 3.63 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 39 40 41 42 43
* 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
git checkout master -b your-change-name
```

### 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 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113
* Click "Submit merge request" 

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

```
git rebase -i HEAD~X
```

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

### Re-Submitting

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

```
114
git push -f origin yourbranchname:same-descriptive-name
115
```
116 117 118 119 120 121 122 123 124 125 126 127

## 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
128
git push origin yourbranchname:descriptive-name
129 130 131 132 133 134 135 136 137 138 139 140
```

### Merge Main Repo

Merge the main repo into yours, branch it and apply your changes.

```sh
git checkout master
git pull
git fetch upstream
git merge upstream/master
git checkout master -b yourbranchname
141
git push origin yourbranchname:descriptive-name
142 143
```