CONTRIBUTING.md

   1 # ISC DHCP Contributor's Guide
   2
   3 So you found a bug in ISC DHCP or plan to develop an extension and want to send us a patch? Great!
   4 This page will explain how to contribute your changes smoothly.
   5
   6 We do not require a contributors agreement. By submitting a patch or merge request to this project,
   7 you are agreeing that your code will be covered by the primary license for the project.
   8 ISC DHCP is currently licensed under the MPL2.0 license.
   9
  10 **NOTE**: The client (dhclient) and relay (dhcrelay) component maintenance is coming to an end.
  11 The 4.4.3 release is the last one that included those components and they are now considered EOL.
  12 The 4.5.0 release will feature server (dhcpd) only. You may still submit bugs for a client or
  13 relay, but those will be kept for informational purposes only. There will not be any action
  14 taken by ISC team on those.
  15
  16 Here's are the steps in contributing a patch:
  17
  18 1. **create account** on [gitlab](https://gitlab.isc.org)
  19 2. **open an issue** in [this project](https://gitlab.isc.org/isc-projects/dhcp/issues/new), make sure
  20    it describes what you want to fix and **why**. ISC DHCP is very mature code, with a large installed base.
  21    We are fairly conservative about making changes unless there is a very good reason.
  22 3. **ask someone from the ISC team to give you a 'project allocation' so you can to fork ISC DHCP in our repo** (ask on the issue - mention @tomek, @vicky, @ondrej
  23    or @godfryd if it seems we haven't noticed your request)
  24 4. **fork the DHCP master branch**: go to the DHCP project page, click the [Fork button](https://gitlab.isc.org/isc-projects/dhcp/forks/new).
  25    If you can't, you didn't complete step 3. It helps to include the issue number and subject in the branch name.
  26 5. **Implement your fix or feature, in your branch**. Make sure it compiles, has unit-tests,
  27    is documented and does what it's supposed to do.
  28 6. **Open Merge Request**: go to the DHCP project [merge requests page](https://gitlab.isc.org/isc-projects/dhcp/merge_requests), and
  29    click [New merge request](https://gitlab.isc.org/isc-projects/dhcp/merge_requests/new). If you
  30    don't see the button, you didn't complete step 3.
  31 7. **Participate in the code review**: Once you submit the MR, someone from ISC will eventually get
  32    to the issue and will review your code. Please make sure you respond to comments. It's likely
  33    you'll be asked to update the code.
  34
  35 See the text below for more details.
  36
  37
  38 ## Create an issue
  39
  40 The first step in contributing to ISC DHCP is to [create an issue](https://gitlab.isc.org/isc-projects/dhcp/issues/new), describing the problem, deficiency
  41 or missing feature you want to address.  It is important to make it very clear why the specific change
  42 you are proposing should be made. ISC DHCP is very mature code, with a large and somewhat inert installed base.
  43 We are very cautious about introducing changes that could break existing functionalty.  If you want to fix
  44 multiple problems, or make multiple changes, please make separate issues for each.
  45
  46 ## Plan your changes
  47
  48 Before you start working on a patch or a new feature, it is a good idea to discuss it first with
  49 DHCP developers.  You may benefit from reading the [ISC DHCP Developer's Survival Guide](https://gitlab.isc.org/isc-projects/dhcp/wikis/home)
  50 posted on the wiki page for this repo.
  51
  52 You can post questions about development on the [dhcp-workers](https://lists.isc.org/mailman/listinfo/dhcp-workers)
  53 or [dhcp-users](https://lists.isc.org/mailman/listinfo/dhcp-users) mailing lists. Dhcp-users is
  54 intended for users who are not interested in development details: it is appropriate to ask for
  55 feedback regarding the best proposed solution to a certain problem. The internal details,
  56 questions about the code and its internals are better asked  on dhcp-workers. The dhcp-workers
  57 list is a very low traffic list.
  58
  59
  60 ## Create a branch for your work
  61
  62 These instructions assume you will be making your changes on a branch in the ISC DHCP Gitlab
  63 repository. This is by far the easiest way for us to collaborate with you.  While we also maintain a presence
  64 on [Github](https://github.com/isc-projects/dhcp), ISC developers rarely look at Github, which is
  65 just a mirror of our Gitlab system.
  66
  67 ISC's Gitlab has been a target for spammers, so it is set up defensively. New users need permission
  68 from ISC to create new projects.  We gladly do this for anyone who asks and provides a good reason.
  69 "I'd like to fix bug X or develop feature Y" is an excellent reason. To request a project
  70 allocation in ISC's Gitlab, just ask for it in a comment in your issue. Make sure
  71 you tag someone at ISC (@tomek, @godfryd, @vicky or @ondrej). When you write a comment in an issue or
  72 merge request and add a name tag on it, the user is automatically notified.
  73
  74 Once you are given a 'project allocation' in our Gitlab, you can fork ISC DHCP and create a branch.
  75 This is your copy of ISC DHCP and is where you will make your changes. Go to the DHCP project page,
  76 click the [Fork button](https://gitlab.isc.org/isc-projects/dhcp/forks/new) and you will be prompted
  77 to name your branch. It helps to include the issue number and subject in the branch name. You can make
  78 changes to this branch without worrying that you will impact the master branch - commit priviliges
  79 are restricted so you cannot accidentally alter the master branch.
  80
  81 Please read the [Gitlab How-To](https://gitlab.isc.org/isc-projects/dhcp/wikis/processes/gitlab-howto) for ISC DHCP.
  82
  83
  84 ## Implement your change
  85
  86 Please try to conform to the project's coding standards. ISC DHCP uses the same [coding standards](https://gitlab.isc.org/isc-projects/bind9/blob/master/doc/dev/style.md) as the BIND 9 project. https://gitlab.isc.org/isc-projects/bind9/blob/master/doc/dev/style.md
  87
  88
  89 ## Compile your code
  90
  91 We don't yet have continuous integration set up for ISC DHCP, so you have to check the compilation manually.
  92 ISC DHCP is used on a wide array of UNIX and Linux operating systems. Will your code compile and work there?
  93 What about endianness? It is likely that you used a regular x86 architecture machine to write your
  94 patch, but the software is expected to run on many other architectures. .
  95
  96 ## Run unit-tests
  97
  98 One of the ground rules in all ISC projects is that every piece of code has to be tested. For newer
  99 projects, we require a unit-test for almost every line of code. For older code, such as
 100 ISC DHCP, that was not developed with testability in mind, it's unfortunately impractical to require
 101 extensive unit-tests. Having said that, please think thoroughly if there is any way to develop
 102 unit-tests. The long term goal is to improve the situation.
 103
 104 Where unit tests are not practical, supplying us with things like configuration file(s), lease file(s),
 105 PCAPS, and step-by-step on how you tested the changes would be a big help.  This will aid us in
 106 creating and adding system tests to the build farm.
 107
 108 You should have also conducted some sort of system testing to verify that your changes do what you
 109 want. It would be extremely helpful if you can attach any configuration files (dhcpd and or
 110 dhclient), along with a step-by-step procedure to carry out the test(s).  This will help us verify
 111 your changes as extend our own system tests.
 112
 113 Make sure you have ATF (Automated Test Framework) installed in your system. For more information
 114 about ATF, please refer to <dhcp source tree>/doc/devel/atf.dox.  Note, running "make devel" in this
 115 directory will generate the documentation. To run the unit-tests, simply run:
 116
 117 ```bash
 118 ./configure --with-atf
 119 make
 120 make check
 121 ```
 122
 123 If you happen to add new files or have modified any Makefile.am files, it is also a good idea to
 124 check if you haven't broken the distribution process:
 125
 126 ```bash
 127 make distcheck
 128 ```
 129
 130 There are other useful switches which can be passed to configure. A complete list of all switches
 131 can be obtained with the command:
 132
 133 ```bash
 134 ./configure --help
 135 ```
 136
 137 ## Create a Merge Request
 138
 139 Once you feel that your patch is ready, go to the DHCP project
 140 and [submit a Merge Request](https://gitlab.isc.org/isc-projects/dhcp/merge_requests/new).
 141
 142 If you can't access this link or don't see New Merge Request button on the [merge requests
 143 page](https://gitlab.isc.org/isc-projects/dhcp/merge_requests), please ask on dhcp-workers and someone
 144 will help you out.
 145
 146 Once you submit it, someone from the DHCP development team will look at it and will get back to you.
 147 The dev team is very small, so it may take a while...
 148
 149 ## If you really can't do a merge request on ISC's Gitlab...
 150
 151 Well, you are out of luck. There are other ways, but those are really awkward and the chances of
 152 your patch being ignored are really high. Anyway, here they are:
 153
 154 - Create a ticket in the DHCP Gitlab (https://gitlab.isc.org/isc-projects/dhcp) and attach your
 155   patch to it. Sending a patch has a number of disadvantages. First, if you don't specify the base
 156   version against which it was created, one of ISC engineers will have to guess that or go through
 157   a series of trials and errors to find that out. If the code doesn't compile, the reviewer will not
 158   know if the patch is broken or maybe it was applied to incorrect base code. Another frequent
 159   problem is that it may be possible that the patch didn't include any new files you have added.
 160
 161 - Send a patch to the dhcp-workers list. This is even worse, but still better than not getting the
 162   patch at all. The problem with this approach is that we don't know which version the patch was
 163   created against and there is no way to track it. So the chances of it being forgotten are high.
 164   Once a DHCP developer get to it, the first thing he/she will have to do is try to apply your
 165   patch, create a branch commit your changes and then open MR for it.
 166
 167 ## Going through a review
 168
 169 Once the merge request (MR) is in the system, the action is on one of the core developers.
 170
 171 Sooner or later, one of these engineers will do the review. Unfortunately, we have a small team
 172 and we have a lot of users to support, so it may take a while for us to get to your patch.
 173 Having said that, we value external contributions very much and will do whatever we
 174 can to review patches in a timely manner.
 175
 176 Don't get discouraged if your patch is not accepted on the first review. To keep the code
 177 quality high, we use the same review processes for external patches as we do for internal code.
 178 It may take some cycles of review/updated patch submissions before the code is finally accepted.
 179 The nature of the review process is that it emphasizes areas that need improvement. If you are
 180 not used to the review process, you may get the impression that the feedback is negative. It
 181 is not: even the core developers seldom see reviews that say "All OK please merge".
 182
 183 If we happen to have any comments that you as submitter are expected to address (and in the
 184 overwhelming majority of cases, we have), you will be asked to update your MR. It is common
 185 to see several rounds of such reviews.
 186
 187 Once the process is almost complete, the developer will likely ask you how you would like to be
 188 credited. The typical answers are by first and last name, by nickname, by company name or
 189 anonymously. Typically we will add a note to the ChangeLog and also set you as the author of the
 190 commit applying the patch and update the contributors section in the AUTHORS file. If the
 191 contributed feature is big or critical for whatever reason, it may also be mentioned in release
 192 notes.
 193
 194 Sadly, we sometimes see patches that are submitted and then the submitter never responds to our
 195 comments or requests for an updated patch. Depending on the nature of the patch, we may either fix
 196 the outstanding issues on our own and get another engineer to review them or the ticket may end
 197 up in our Outstanding milestone. When a new release is started, we go through the tickets in
 198 Outstanding, select a small number of them and move them to whatever the current milestone is. Keep
 199 that in mind if you plan to submit a patch and forget about it. We may accept it eventually, but
 200 it's a much, much faster process if you participate in it.
 201
 202 **Thank you for contributing your time and expertise to the ISC DHCP Project.**