... | ... | @@ -22,11 +22,15 @@ cd kea |
|
|
|
|
|
- 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 not assigned to any milestone, unless you discussed this with the project manager and he is ok with adding it directly to the current milestone. We have a process to triage unassigned tickets weekly and assign them to specific milestone.
|
|
|
|
|
|
- Issues must have descriptions. You may save seconds of your time, but others will waste much more trying to figure out what's actually there to do or why. Playing a guessing game is really a time waste. Issues that don't have a description will not be accepted in milestones, except Outstanding. No exceptions.
|
|
|
- Issues must have descriptions. You may save seconds of your time, but others will waste much more trying to figure out what's actually there to do or why. Playing a guessing game is really a waste of time. Issues that don't have a description will not be accepted in milestones, except Outstanding. No exceptions.
|
|
|
|
|
|
- Labels are a very good way to group tickets or get a quick overview what functionality is affected. Technically, they're optional, but it's highly recommended to put them in. There may be multiple labels assigned.
|
|
|
|
|
|
- Gitlab allows cross-referencing issues. This is very convenient to link similar issues or issues that apply to specific problem. Sometimes we get lucky and are able to close multiple tickets for a single fix. Also, once you touch certain area, it's often useful to see what other problems are there.
|
|
|
|
|
|
# Working on an issue
|
|
|
|
|
|
- Once you start 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.
|
|
|
- Once you start 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 (drag-n-drop) your issue to appropriate stage.
|
|
|
|
|
|
- Open the issue page, e.g. https://gitlab.isc.org/isc-projects/kea/issues/3 and click create a MR. A good trick is to click on the triangle button to get the extended create MR menu. Start the title with `Draft:` or `WIP:` to prevent merging for now. In particular, you can use a shorter branch name. The branch name MUST start with the issue number.
|
|
|
|
... | ... | @@ -38,11 +42,11 @@ cd kea |
|
|
|
|
|
# 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. Gitlab allows to also specify yourself as a reviewer. It's an additional step that useful for at least two reasons: later on, once the change is approved, your approval will show on the reviewers list as approved. Also, you can filter tickets by reviews, which makes easy to find tickets you reviewed. One limitation is that there can be only one reviewer specified in the free Gitlab version we're using.
|
|
|
- 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. For things that you expect some changes or action, use thread rather than comment. Once you're done, reassign back to the developer. As an additional, optional, but recommended step, Gitlab allows to also specify yourself as a reviewer. It's an additional step that useful for at least two reasons: later on, once the change is approved, your approval will show on the reviewers list as approved. Also, you can filter tickets by reviews, which makes easy to find tickets you reviewed. One limitation is that there can be only one reviewer specified in the free Gitlab version we're using.
|
|
|
|
|
|
- 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 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. For threads, explain what you did, but do not resolve threads (unless it's something trivial, like typos). It's up to reviewer to accept or reject your proposed fix for a given comment. 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 the Draft/WIP prefix". Also, there's Approve button that you should click. Removal of the WIP status is a clear indication the code is ready to go.
|
|
|
- as a reviewer: Once all your comments are addressed (make sure you resolve the thread), put a note that the code is ready to merge, open the MR, edit it and click on "remove the Draft/WIP prefix". Also, there's Approve button that you should click. Removal of the WIP status is a clear indication the code is ready to go.
|
|
|
|
|
|
- If you can't reach an agreement after several review rounds, you can do two things: ask for a third opinion (any developer will do) or ask the manager to solve the problem.
|
|
|
|
... | ... | @@ -50,7 +54,7 @@ cd kea |
|
|
|
|
|
- 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 significant CI integrated with gitlab. We have shellcheck and are planning to integrate danger in gitlab CI. If any of them fail, you won't be able to merge anything. Please fix the issue before merging. Before merging, please run unit-tests on your own.
|
|
|
- We do have a Gitlab CI in place that uses several tooks. If you see the pipeline failing, you won't be able to merge anything. Please fix the issue before merging. Before merging, please run unit-tests on your own.
|
|
|
|
|
|
- Using rebase button on MR page is a very nice way of rebasing your branch. If there are conflicts, here's how you can rebase the code:
|
|
|
```console
|
... | ... | @@ -66,7 +70,7 @@ git rebase --skip # if there are specific commits that you decided to skip, e.g. |
|
|
|
|
|
- Once you push your changes to master, gitlab should close the merge request and the ticket.
|
|
|
|
|
|
**PROCESS CHANGE**: We previously (before Oct 2019) put three things in the Changelog: Gitlab issue number, MR number and sha of the commit-id. This uniquely identified the changes, but was annoying and it was difficult to automate (in principle it could be done, but you'd have to develop a script that would use gitlab API to retrieve the MR #). After discussion with several members of the team, I propose to put only issue #. All other details are available using GL web interface.
|
|
|
**PROCESS CHANGE**: We previously (before Oct 2019) put three things in the Changelog: Gitlab issue number, MR number and sha of the commit-id. Since then, we're only putting the Gitlab issue number. All other details are available using GL web interface.
|
|
|
|
|
|
# GIT commit logs
|
|
|
|
... | ... | @@ -78,7 +82,7 @@ Since we sometimes get code from places outside of our control (MRs on gitlab, P |
|
|
|
|
|
We don't do commit squashes in general. Sometimes the reviewer pushes fixes or we get commits from contributors (it's essential to get those preserved. Users being able to point to their code and brag about it is one of the reasons they submit patches).
|
|
|
|
|
|
If you like, you can squash your own commits.
|
|
|
If you like, you can squash _your own commits.
|
|
|
|
|
|
# Changelog
|
|
|
|
... | ... | @@ -100,17 +104,31 @@ An example changelog entry looks like this: |
|
|
Branch names must start with an issue number. Yes, there has to be an issue, even if you're doing an experiment and are uncertain if the code will ever be merged. It takes 30 seconds to create one. Tomek wants to be able to dig up what you were working on when writing release notes.
|
|
|
|
|
|
# Using labels
|
|
|
Violet labels are for priority. There are four priority labels: critical, high, medium and low.
|
|
|
|
|
|
Orange labels are for components.
|
|
|
The following text only describes the most frequently used labels. For a full list, see [the labels list](https://gitlab.isc.org/isc-projects/kea/-/labels).
|
|
|
|
|
|
Violet labels are for priority. There are four priority labels: ~critical, ~high, ~medium (not really used) and ~low. If a ticket doesn't have a label, we assume it's ~medium. We also have a ~customer label, which indicates the problem or request came from a customer. This means it is important and typically we treat it as a high priority.
|
|
|
|
|
|
Orange labels are for components. There are many such labels.
|
|
|
|
|
|
Green labels designate type and state of the issue: ~Doing, ~Review.
|
|
|
|
|
|
Dull yellow labels designate specific libraries. There are many such labels.
|
|
|
|
|
|
Washed greens are for specific hook commands: ~cb_cmds, ~bootp, ~class_cmds, ~flex-id, ~flex-option, ~forensic-log, ~hooks, ~host-cmds, ~lease_cmds, ~limits, ~lq, ~radius, ~rbac, ~stat_cmds, ~subnet_cmds.
|
|
|
|
|
|
Red labels are for things that should stand out. Currently there's one label: ~bug, ~"won't fix"
|
|
|
|
|
|
Green labels designate type and state of the issue (feature request, QA needed, etc)
|
|
|
Blue labels are for issues that are OS specific: ~Linux, ~FreeBSD, ~MacOS, ~Exotic.
|
|
|
|
|
|
Yellow labels designate specific libraries.
|
|
|
There are couple other labels that may be useful:
|
|
|
|
|
|
Red labels are for things that should stand out. Currently there's one label: ~bug.
|
|
|
- ~design - put on tickets that are complex enough that require a written design
|
|
|
- ~stork - used for tickets that are useful for or affect Stork, our UI interface for Kea
|
|
|
- ~security - used for tickets that have security implications. If you feel this may be a security vulnerability, it's good to flip the ticket to confidential.
|
|
|
- ~"qa needed" - put on tickets that requires some action from QA dept, such as request to develop a new test, check if provided solution is working etc.
|
|
|
|
|
|
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.
|
|
|
Tomek's idea was to use dark colors for important things and light colors for less important aspects.
|
|
|
|
|
|
## Working with multiple repositories (optional)
|
|
|
|
... | ... | |