github.com/gophercloud/gophercloud@v1.11.0/docs/contributor-tutorial/step-05-pull-requests.md (about)

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