Commit 2cdc6b86 authored by Tomek Mrugalski's avatar Tomek Mrugalski 🛰
Browse files

Cleaned up the text.

parent 22f46135
......@@ -8,7 +8,7 @@ Here's a quick list of how to contribute a patch:
2. **open a bug ticket** in [Kea project](https://gitlab.isc.org/isc-projects/kea/issues/new), make sure it describes what you want to fix and **why**
3. **ask someone from the ISC team to give you permission to fork Kea** (ask @tomek, @vicky, @ondrej or @godfryd or basically anyone from the Kea dev team)
4. **fork Kea code**: go to Kea project page, click [Fork button](https://gitlab.isc.org/isc-projects/kea/forks/new). If you can't, you didn't complete step 3.
5. **Implement your fix or feature, push code** to your repo.
5. **Implement your fix or feature, push code** to your repo. Make sure it compiles, has unit-tests, is documented and does what it's supposed to do.
6. **Open Merge Request**: go to Kea project [merge requests page](https://gitlab.isc.org/isc-projects/kea/merge_requests), click [New merge request](https://gitlab.isc.org/isc-projects/kea/merge_requests/new). If you don't see the button, you didn't complete step 3.
7. **Participate in the code review**: Once you submit the MR, someone from ISC will eventually get to the ticket and will review your code. Please make sure you respond to comments. It's likely you'll be asked to update the code.
......@@ -89,7 +89,7 @@ To enable the MySQL backend, use the switch `–with-mysql`; for PostgreSQL, use
./configure --help
```
## Merge Request (also known as sending your patch the right way)
## Submitting Merge Request (also known as sending your patch the right way)
The first step in writing the patch or new feature should be to get the source code from our Git repository.
The procedure is very easy and is [explained here](https://gitlab.isc.org/isc-projects/kea/wikis/gitlab-howto).
......@@ -102,14 +102,12 @@ the process of syncing gitlab to github is mostly automated and Kea devs rarely
ISC's gitlab has been a target for spammers in the past, so it is now set up defensively. In particular, new users
can't fork the code on their own and it requires someone from ISC to manually grant the ability to fork projects.
Fortunately, this is easy to do and we glady do this for anyone who asks and provides a good reason. "I'd like to fix
bug X or develop feature Y" is an excellent reason. The best place for asking is either kea-dev or
bug X or develop feature Y" is an excellent reason. The best place for asking is either kea-dev or asking in your
ticket. Make sure you put a name tag (@tomek, @godfryd or @vicky). When you write a comment in a ticket or merge
request and add a name tag on it, the user is automatically notified.
Since you won't get write access to the Kea repository, you should fork it and then commit your changes to
your own repo. How you organize the work depends entirely on you, but it seems reasonable to create a branch
rather than working on your master. Once the code on your branch and feel its ready
Once you feel that your patch is ready, please commit your changes and push it to your copy of Kea repo.
Then go to Kea project and [submit a Merge Request](https://gitlab.isc.org/isc-projects/kea/merge_requests/new).
Once you fork the Kea code in gitlab, you have your own copy and you can commit your changes there and push them
to your copy of Kea repo. Once you feel that your patch is ready, go to Kea project and [submit a Merge Request](https://gitlab.isc.org/isc-projects/kea/merge_requests/new).
If you can't access this link or don't see New Merge Request button on the [merge requests page](https://gitlab.isc.org/isc-projects/kea/merge_requests),
please ask on kea-dev and someone will help you out.
......@@ -138,9 +136,8 @@ listed as contributor and Kea will be listed as project you have contributed to.
## If you really can't do MR on gitlab or PR on github...
Well, you are out of luck. There are other ways, but those are really awkward and the chances of your patch
being ignored are really high. Anyway, here they are:
- Create a ticket in the Kea Gitlab (https://gitlab.isc.org/isc-projects/kea) and attach your patch to it. Sending
being ignored are really high. Anyway, the third, least preferred alternative is to
[create a ticket in the Kea Gitlab](https://gitlab.isc.org/isc-projects/kea/issues/new) and attach your patch to it. Sending
a patch has a number of disadvantages. First, if you don't specify the base version against which it was created,
one of ISC engineers will have to guess that or go through a series of trials and errors to find that out. If the
code doesn't compile, the reviewer will not know if the patch is broken or maybe it was applied to incorrect base
......@@ -155,13 +152,40 @@ being ignored are really high. Anyway, here they are:
## Going through a review
Once you let us submitted a patch using one of the ways above, the action is on one of the ISC engineers. First, we will need either a trac ticket or PR on github. We prefer the original submitter fill them as he or she has the best understanding of the purpose of the change and may have any extra information, e.g. "this patch fixes compilation issue on FreeBSD 10.1". If there there is no PR and no trac ticket, we will create one. Depending on the subjective importance and urgency as perceived by the ISC engineer, the ticket or PR will be assigned to one of the milestones.
Sooner or later, one of ISC engineers will do the review. Here's the tricky part. One of Kea developers will review your patch, but it may not happen immediately. Unfortunately, developers are usually working under a tight schedule, so any extra unplanned review work may take a while sometimes. Having said that, we value external contributions very much and will do whatever we can to review patches in a timely manner. Don't get discouraged if your patch is not accepted after first review. To keep the code quality high, we use the same review processes for external patches as we do for internal code. It may take some cycles of review/updated patch submissions before the code is finally accepted. The nature of the review process is that it emphasizes areas that need improvement. If you are not used to the review process, you may get the impression that the feedback is negative. It is not: even the Kea developers seldom see reviews that say "All OK please merge".
Once the process is almost complete, the developer will likely ask you how you would like to be credited. The typical answers are by first and last name, by nickname, by company name or anonymously. Typically we will add a note to the ChangeLog and also set you as the author of the commit applying the patch and update the contributors section in the AUTHORS file. If the contributed feature is big or critical for whatever reason, it may also be mentioned in release notes.
Sadly, we sometimes see patches that are submitted and then the submitter never responds to our comments or requests for an updated patch. Depending on the nature of the patch, we may either fix the outstanding issues on our own and get another ISC engineer to review them or the ticket may end up in our "Outstanding Tasks" milestone. When a new release is started, we go through the tickets in Outstanding Tasks, select a small number of them and move them to whatever the current milestone is. Keep that in mind if you plan to submit a patch and forget about it. We may accept it eventually, but it's much, much faster process if you participate in it.
Once you let us submitted a patch using one of the ways above, the action is on one of the ISC engineers. First,
we will need either a trac ticket or PR on github. We prefer the original submitter fill them as he or she has
the best understanding of the purpose of the change and may have any extra information, e.g. "this patch fixes
compilation issue on FreeBSD 10.1". If there there is no PR and no trac ticket, we will create one. Depending on
the subjective importance and urgency as perceived by the ISC engineer, the ticket or PR will be assigned to one
of the milestones.
Sooner or later, one of ISC engineers will do the review. Here's the tricky part. One of Kea developers will
review your patch, but it may not happen immediately. Unfortunately, developers are usually working under a tight
schedule, so any extra unplanned review work may take a while sometimes. Having said that, we value external
contributions very much and will do whatever we can to review patches in a timely manner. Don't get discouraged
if your patch is not accepted after first review. To keep the code quality high, we use the same review processes
for external patches as we do for internal code. It may take some cycles of review/updated patch submissions
before the code is finally accepted. The nature of the review process is that it emphasizes areas that need
improvement. If you are not used to the review process, you may get the impression that the feedback is negative.
It is not: even the Kea developers seldom see reviews that say "All OK please merge".
Once the process is almost complete, the developer will likely ask you how you would like to be credited.
The typical answers are by first and last name, by nickname, by company name or anonymously. Typically we will
add a note to the ChangeLog and also set you as the author of the commit applying the patch and update the
contributors section in the AUTHORS file. If the contributed feature is big or critical for whatever reason,
it may also be mentioned in release notes.
Sadly, we sometimes see patches that are submitted and then the submitter never responds to our comments or requests
for an updated patch. Depending on the nature of the patch, we may either fix the outstanding issues on our own and
get another ISC engineer to review them or the ticket may end up in our "Outstanding Tasks" milestone. When a new
release is started, we go through the tickets in Outstanding Tasks, select a small number of them and move them
to whatever the current milestone is. Keep that in mind if you plan to submit a patch and forget about it. We may
accept it eventually, but it's much, much faster process if you participate in it.
Extra steps
If you are interested in knowing the results of more in-depth testing, you are welcome to visit the ISC Jenkins page: https://jenkins.isc.org This is a live result page with all tests being run on various systems. Besides basic unit-tests, we also have reports from valgrind (memory debugger), cppcheck and clang-analyzer (static code analyzers), Lettuce system tests and more. Although it is not possible for non ISC employees to run tests on that farm, it is possible that your contributed patch will end up there sooner or later. We also have ISC Forge tests running, but currently the test results are not publicly available.
If you are interested in knowing the results of more in-depth testing, you are welcome to visit the ISC Jenkins
page: https://jenkins.isc.org This is a live result page with all tests being run on various systems. Besides
basic unit-tests, we also have reports from valgrind (memory debugger), cppcheck and clang-analyzer (static code
analyzers), Lettuce system tests and more. Although it is not possible for non ISC employees to run tests on that
farm, it is possible that your contributed patch will end up there sooner or later. We also have ISC Forge tests
running, but currently the test results are not publicly available.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment