]>
Commit | Line | Data |
---|---|---|
dd23902d | 1 | # ISC DHCP Contributor's Guide |
6ee76860 | 2 | |
dd23902d TM |
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. | |
6ee76860 | 5 | |
0cd94b5e TM |
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 | ||
6227b190 TM |
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 | ||
0cd94b5e TM |
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 | |
6ee76860 | 47 | |
228aa403 | 48 | Before you start working on a patch or a new feature, it is a good idea to discuss it first with |
0cd94b5e TM |
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 | |
6ee76860 | 97 | |
228aa403 | 98 | One of the ground rules in all ISC projects is that every piece of code has to be tested. For newer |
0cd94b5e | 99 | projects, we require a unit-test for almost every line of code. For older code, such as |
228aa403 TM |
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 | ||
0cd94b5e TM |
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 | ||
dd23902d TM |
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 | ||
dd23902d TM |
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: | |
228aa403 TM |
116 | |
117 | ```bash | |
0cd94b5e TM |
118 | ./configure --with-atf |
119 | make | |
228aa403 TM |
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: | |
6ee76860 TM |
125 | |
126 | ```bash | |
127 | make distcheck | |
128 | ``` | |
129 | ||
228aa403 TM |
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: | |
6ee76860 TM |
132 | |
133 | ```bash | |
134 | ./configure --help | |
135 | ``` | |
136 | ||
0cd94b5e | 137 | ## Create a Merge Request |
228aa403 | 138 | |
0cd94b5e | 139 | Once you feel that your patch is ready, go to the DHCP project |
dd23902d | 140 | and [submit a Merge Request](https://gitlab.isc.org/isc-projects/dhcp/merge_requests/new). |
6ee76860 | 141 | |
0cd94b5e TM |
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. | |
6ee76860 | 145 | |
228aa403 TM |
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... | |
6ee76860 | 148 | |
0cd94b5e | 149 | ## If you really can't do a merge request on ISC's Gitlab... |
6ee76860 | 150 | |
228aa403 TM |
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 | |
6ee76860 | 168 | |
0cd94b5e TM |
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. | |
228aa403 | 175 | |
0cd94b5e TM |
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". | |
228aa403 TM |
182 | |
183 | If we happen to have any comments that you as submitter are expected to address (and in the | |
0cd94b5e TM |
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. | |
228aa403 TM |
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 | |
0cd94b5e | 196 | the outstanding issues on our own and get another engineer to review them or the ticket may end |
228aa403 TM |
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 | |
0cd94b5e | 200 | it's a much, much faster process if you participate in it. |
228aa403 | 201 | |
6227b190 | 202 | **Thank you for contributing your time and expertise to the ISC DHCP Project.** |