1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
|
Step 5: Writing the Code
========================
At this point, you should have:
- [x] Identified a feature or bug fix
- [x] Opened an Issue about it
- [x] Located the project's service code which validates the feature or fix
- [x] Have an OpenStack environment available to test with
Now it's time to write the actual code! We recommend reading over the
[CONTRIBUTING](/.github/CONTRIBUTING.md) guide again as a refresh. Notably
the [Getting Started](/.github/CONTRIBUTING.md#getting-started) section will
help you set up a `git` repository correctly.
We encourage you to browse the existing Gophercloud code to find examples
of similar implementations. It would be a _very_ rare occurrence for you
to be implementing something that hasn't already been done.
Use the existing packages as templates and mirror the style, naming, and
logic.
Types of Pull Requests
----------------------
The amount of changes you plan to make will determine how much code you should
submit as Pull Requests.
### A Single Bug Fix
If you're implementing a single bug fix, then creating one `git` branch and
submitting one Pull Request is fine.
### Adding a Single Field
If you're adding a single field, then a single Pull Request is also fine. See
[#662](https://github.com/gophercloud/gophercloud/pull/662) as an example of
this.
If you plan to add more than one missing field, you will need to open a Pull
Request for _each_ field.
### Adding a Single API Call
Single API calls can also be submitted as a single Pull Request. See
[#722](https://github.com/gophercloud/gophercloud/pull/722) as an example of
this.
### Adding a Suite of API Calls
If you're adding support for a "suite" of API calls (meaning: Create, Update,
Delete, Get), then you will need to create one Pull Request for _each_ call.
The following Pull Requests are good examples of how to do this:
* https://github.com/gophercloud/gophercloud/pull/584
* https://github.com/gophercloud/gophercloud/pull/586
* https://github.com/gophercloud/gophercloud/pull/587
* https://github.com/gophercloud/gophercloud/pull/594
You can also use the provided [template](/docs/contributor-tutorial/.template)
as it contains a lot of the repeated boiler plate code seen in each resource.
However, please make sure to thoroughly review and edit it as needed.
Leaving templated portions in-place might be interpreted as rushing through
the work and will require further rounds of review to fix.
### Adding an Entire OpenStack Project
To add an entire OpenStack project, you must break each set of API calls into
individual Pull Requests. Implementing an entire project can be thought of as
implementing multiple API suites.
An example of this can be seen from the Pull Requests referenced in
[#723](https://github.com/gophercloud/gophercloud/issues/723).
What to Include in a Pull Request
---------------------------------
Each Pull Request should contain the following:
1. The actual Go code to implement the feature or bug fix
2. Unit tests
3. Acceptance tests
4. Documentation
Whether you want to bundle all of the above into a single commit or multiple
commits is up to you. Use your preferred style.
### Unit Tests
Unit tests should provide basic validation that your code works as intended.
Please do not use JSON fixtures from the API reference documentation. Please
generate your own fixtures using the OpenStack environment you're
[testing](step-04-acceptance-testing.md) with.
### Acceptance Tests
Since unit tests are not run against an actual OpenStack environment,
acceptance tests can arguably be more important. The acceptance tests that you
include in your Pull Request should confirm that your implemented code works
as intended with an actual OpenStack environment.
### Documentation
All documentation in Gophercloud is done through in-line `godoc`. Please make
sure to document all fields, functions, and methods appropriately. In addition,
each package has a `doc.go` file which should be created or amended with
details of your Pull Request, where appropriate.
Dealing with Related Pull Requests
----------------------------------
If you plan to open more than one Pull Request, it's only natural that code
from one Pull Request will be dependent on code from the prior Pull Request.
There are two methods of handling this:
### Create Independent Pull Requests
With this method, each Pull Request has all of the code to fully implement
the code in question. Each Pull Request can be merged in any order because
it's self contained.
Use the following `git` workflow to implement this method:
```shell
$ git checkout master
$ git pull
$ git checkout -b identityv3-regions-create
$ (write your code)
$ git add .
$ git commit -m "Implementing Regions Create"
$ git checkout master
$ git checkout -b identityv3-regions-update
$ (write your code)
$ git add .
$ git commit -m "Implementing Regions Update"
```
Advantages of this Method:
* Pull Requests can be merged in any order
* Additional commits to one Pull Request are independent of other Pull Requests
Disadvantages of this Method:
* There will be _a lot_ of duplicate code in each Pull Request
* You will have to rebase all other Pull Requests and resolve a good amount of
merge conflicts.
### Create a Chain of Pull Requests
With this method, each Pull Request is based off of a previous Pull Request.
Pull Requests will have to be merged in a specific order since there is a
defined relationship.
Use the following `git` workflow to implement this method:
```shell
$ git checkout master
$ git pull
$ git checkout -b identityv3-regions-create
$ (write your code)
$ git add .
$ git commit -m "Implementing Regions Create"
$ git checkout -b identityv3-regions-update
$ (write your code)
$ git add .
$ git commit -m "Implementing Regions Update"
```
Advantages of this Method:
* Each Pull Request becomes smaller since you are building off of the last
Disadvantages of this Method:
* If a Pull Request requires changes, you will have to rebase _all_ child
Pull Requests based off of the parent.
The choice of method is up to you.
---
Once you have your code written, submit a Pull Request to Gophercloud and
proceed to [Step 6](step-06-code-review.md).
|
