|
|
This page describes Kea project workflow. Everyone who contribute to Kea project is expected to read it at least once.
|
|
|
|
|
|
# Gitlab setup
|
|
|
- create an account if you don't have it yet.
|
|
|
- go to gitlab.isc.org, click on your user icon in right top corner and click settings from the drop menu. Then click ssh keys icon on the left panel.
|
|
|
- There are links there that explain how to generate your keys if you somehow haven't done that already. Anyway, the idea is to paste the content of your ~/.ssh/key-name.pub file there.
|
|
|
- As a completely optional step, I configured my ssh client to use separate key for gitlab, by adding this to my ~/.ssh/config file:
|
|
|
```
|
|
|
Host gitlab.isc.org
|
|
|
IdentityFile ~/.ssh/id_ed25519_gitlab
|
|
|
```
|
|
|
|
|
|
# Set up your git repository
|
|
|
|
|
|
Note: we previously used tomek/kea repository for expriements. That repo is now private and will be deleted in couple weeks. If there's anything of value there, please move it to the isc-projects/kea repo. Note that gitlab allows moving issues between projects. For commits, you cherry-picking or merging your changes is probably the best way to go.
|
|
|
|
|
|
To clean up existing repository do (this will abandon any changes you may have):
|
|
|
```
|
|
|
git checkout master
|
|
|
git reset --hard
|
|
|
git clean -fxd
|
|
|
git pull
|
|
|
```
|
|
|
|
|
|
To set up a new repository do:
|
|
|
```
|
|
|
git clone git@gitlab.isc.org:isc-projects/kea.git
|
|
|
cd kea
|
|
|
```
|
|
|
|
|
|
Now you can do:
|
|
|
|
|
|
```
|
|
|
# This will pull the current branch you're on from gitlab
|
|
|
git pull
|
|
|
|
|
|
# This will pull whatever you still need to salvage from trac repo
|
|
|
git fetch trac
|
|
|
```
|
|
|
|
|
|
When migrating stuff between repos, DO NOT copy files over. Use cherry-pick instead.
|
|
|
|
|
|
# Adding an issue
|
|
|
|
|
|
- If migrating from trac: If the issue is not in gitlab yet, pick a ticket in trac that you want to copy. Copy the description manually to gitlab (go to https://gitlab.isc.org/isc-projects/kea, click on issues on the left, then "New Issue"). Close the ticket in trac with a link to gitlab issue.
|
|
|
|
|
|
- If you have something new to work on, create an issue in gitlab: go to https://gitlab.isc.org/isc-projects/kea, Make sure it's assigned to kea1.5 milestone. Assign labels as necessary. Add labels if they're missing. We'll decide on the best way to substitute kea-proposed mechanism.
|
|
|
|
|
|
# Working on an issue
|
|
|
|
|
|
- Assign the issue to yourself. You should also assign Doing label. There are two ways of doing that. First, you can add the label manually when browsing an issue. Alternatively, you can go to https://gitlab.isc.org/isc-projects/kea/boards and move your issue to appropriate stage.
|
|
|
|
|
|
- Open the issue page, e.g. https://gitlab.isc.org/isc-projects/kea/issues/3 and click create merge request. a branch will be created for you.
|
|
|
|
|
|
- ```git pull```. Note the branch that was created will be there. Check it out and start working on the code. If you dislike the branch name being too long, consider using shorter description for the issue. However, it must still be human readable and people need to have a chance to understand what the issue is about. Also, if you have bash-completion package installed (and using bash), you can type: git checkout 3, and hit tab. The full name of the branch will be completed for you.
|
|
|
|
|
|
- Commit your changes, push it on that branch.
|
|
|
|
|
|
- Once you are done, do the following: unassign yourself from the issue and MR, remove "doing" label, add "review" label. The doing and review labels should be put on both the issue and the MR. This indicates the MR is ready for a review. This looks like a duplication of work, but it serves different purposes. The issues are tracked using a board (see [this 1.5 board](https://gitlab.isc.org/isc-projects/kea/boards?scope=all&utf8=%E2%9C%93&state=opened&milestone_title=Kea1.5) for example). Once you assign a label to an issue it is shown in the appropriate column. Now, the review label on MR indicates that particular one is ready for review. The illusion of duplication disappears when there are multiple MRs assigned to a single issue.
|
|
|
|
|
|
# Reviewing an issue
|
|
|
|
|
|
- as a reviewer: go to Issues->Board page. Look for an issue in review state that has no assignee. Assign to yourself. Review. Put some snarky comments. Add some more comments. Once you're done, reassign back to the developer.
|
|
|
|
|
|
- as a developer: look for issues that are assigned to you. Do your best with addressing the comments. Push your improvements to the branch. Once done reassign back to the reviewer. Do not merge until the reviewer says the code is ready.
|
|
|
|
|
|
- as a reviewer: Once all your comments are addressed, put a note that the code is ready to merge, open the MR, edit it and click on "remove WIP status". Removal of the WIP status is a clear indication the code is ready to go.
|
|
|
|
|
|
# Merging code
|
|
|
|
|
|
- Kea project is currently set up in a way that allows only fast-forward merges. This is not the only possible option, it looks like the right way to go. It keeps the repo history much cleaner. If you complain about tons of merge conflicts, you tried to push a ticket that was too big.
|
|
|
|
|
|
- Currently we don't have any CI integrated with gitlab. Before merging, please run unit-tests as we did in the trac days.
|
|
|
|
|
|
- Once you push your changes to master, gitlab should close the merge request and the ticket.
|
|
|
|
|
|
- Don't forget to update the commit-id in ChangeLog. Use MR (Merge Request) number, not issue number. The reason for this is that there may be multiple MRs for one issue. Also, in case we import pull requests from github, there may be no issue at all.
|
|
|
|
|
|
- Write down your thoughts. If needed, please update this page.
|
|
|
|
|
|
# Notable differences compared to trac
|
|
|
|
|
|
**Missing fields**. gitlab has fewer fields than trac. That doesn't mean it's more primitive, it just does things in a slightly different way. I (tomek) got used to it and like the new way better. Let me give you an example. Imagine a ticket that requires to update documentation about DHCPv4 parameter in Radius hook. In trac you'd have to choose which component to use: doc, radius, hook, config or dhcp4. In gitlab you can assign five labels and they'd represent what the ticket is about better than you could in trac.
|
|
|
|
|
|
**Priorities**. There are priority labels after all and you can sort by them. Trac had: very high, high, medium, low and very low. In gitlab we have: critical, high, medium and low. Let's see if that's sufficient. If now, we can add very low if needed.
|
|
|
|
|
|
**Ticket and MR have separate numbers**. In trac we were used to the idea that there's one number and that number represents both the ticket and the branch name. Once the branch was merged, the ticket was closed. However, for more complex tickets we often determined that the issue is too big for one branch and we created another ticket and another branch for it. This extra work (to create additional tickets) came up from the limitation that 1 ticket = 1 branch. This is not the case in gitlab. There may be multiple MRs associated with an issue. You may think of an issue as a group ticket.
|
|
|
|
|
|
**No spam**.
|
|
|
|
|
|
**Notifications**. Default notification level is global (i.e. you inherit the global setting which is where?). If you'd like to get everything about a project you can switch to watch in the project detail page.
|
|
|
|
|
|
**Registration for users is working**.
|
|
|
|
|
|
**We are yet to experience the power of CI**. There will be screams in the process and tears of joy at the end.
|
|
|
|
|
|
# Using labels
|
|
|
One major difference,advantage or a flaw (depending on your personal preference) of gitlab is its label system.
|
|
|
|
|
|
Violet labels are for priority. There are four priority labels: critical, high, medium and low.
|
|
|
|
|
|
Orange labels are for components.
|
|
|
|
|
|
Green labels designate type and state of the issue (feature request, QA needed, etc)
|
|
|
|
|
|
Yellow labels designate specific libraries.
|
|
|
|
|
|
Red labels are for things that should stand out. Currently there's one label: bug.
|
|
|
|
|
|
This is just a proposal. Tomek's idea was to use dark colors for important things and light colors for less important aspects. If you don't like it, we can come up with an alternative naming/coloring scheme.
|
|
|
|
|
|
# Working with multiple repositories
|
|
|
Here are a couple commands that may be useful during transition (trac->gitlab) period. However, they are useful if you happen to work with multiple repositories (such as processing pull request from github or working with internal repo).
|
|
|
|
|
|
To list your local branches with the tracking branches on remote repo:
|
|
|
```
|
|
|
git branch -vv
|
|
|
```
|
|
|
|
|
|
To list remote repos you are set to work with:
|
|
|
```
|
|
|
git remote -v
|
|
|
```
|
|
|
|
|
|
To set that your local branch should trac a remote branch, use:
|
|
|
```
|
|
|
git branch -u remote_repo/remote_branch local_branch
|
|
|
``` |