github.com/gophercloud/gophercloud@v1.11.0/docs/contributor-tutorial/step-02-issues.md (about)

     1  Step 2: Create an Issue
     2  ========================
     3  
     4  Every patch / Pull Request requires a corresponding issue. If you're fixing
     5  a bug for an existing issue, then there's no need to create a new issue.
     6  
     7  However, if no prior issue exists, you must create an issue.
     8  
     9  Reporting a Bug
    10  ---------------
    11  
    12  When reporting a bug, please try to provide as much information as you
    13  can.
    14  
    15  The following issues are good examples for reporting a bug:
    16  
    17  * https://github.com/gophercloud/gophercloud/issues/108
    18  * https://github.com/gophercloud/gophercloud/issues/212
    19  * https://github.com/gophercloud/gophercloud/issues/424
    20  * https://github.com/gophercloud/gophercloud/issues/588
    21  * https://github.com/gophercloud/gophercloud/issues/629
    22  * https://github.com/gophercloud/gophercloud/issues/647
    23  
    24  Feature Request
    25  ---------------
    26  
    27  If you've noticed that a feature is missing from Gophercloud, you'll also
    28  need to create an issue before doing any work. This is to start a discussion 
    29  about whether or not the feature should be included in Gophercloud. We don't 
    30  want to see you put in hours of work only to learn that the feature is out of 
    31  scope of the project.
    32  
    33  Feature requests can come in different forms:
    34  
    35  ### Adding a Feature to Gophercloud Core
    36  
    37  The "core" of Gophercloud is the code which supports API requests and
    38  responses: pagination, error handling, building request bodies, and parsing
    39  response bodies are all examples of core code.
    40  
    41  Modifications to core will usually have the most amount of discussion than
    42  other requests since a change to core will affect _all_ of Gophercloud.
    43  
    44  The following issues are examples of core change discussions:
    45  
    46  * https://github.com/gophercloud/gophercloud/issues/310
    47  * https://github.com/gophercloud/gophercloud/issues/613
    48  * https://github.com/gophercloud/gophercloud/issues/729
    49  * https://github.com/gophercloud/gophercloud/issues/713
    50  
    51  ### Adding a Missing Field
    52  
    53  If you've found a missing field in an existing struct, submit an issue to
    54  request having it added. These kinds of issues are pretty easy to report
    55  and resolve.
    56  
    57  You should also provide a link to the actual service's Python code which
    58  defines the missing field.
    59  
    60  The following issues are examples of missing fields:
    61  
    62  * https://github.com/gophercloud/gophercloud/issues/620
    63  * https://github.com/gophercloud/gophercloud/issues/621
    64  * https://github.com/gophercloud/gophercloud/issues/658
    65  
    66  There's one situation which can make adding fields more difficult: if the field
    67  is part of an API extension rather than the base API itself. An example of this
    68  can be seen in [this](https://github.com/gophercloud/gophercloud/issues/749)
    69  issue.
    70  
    71  Here, a user reported fields missing in the `Get` function of
    72  `networking/v2/networks`. The fields reported missing weren't missing at all,
    73  they're just part of various Networking extensions located in
    74  `networking/v2/extensions`.
    75  
    76  ### Adding a Missing API Call
    77  
    78  If you've found a missing API action, create an issue with details of
    79  the action. For example:
    80  
    81  * https://github.com/gophercloud/gophercloud/issues/715
    82  * https://github.com/gophercloud/gophercloud/issues/719
    83  
    84  You'll want to make sure the API call is part of the upstream OpenStack project
    85  and not an extension created by a third-party or vendor. Gophercloud only
    86  supports the OpenStack projects proper.
    87  
    88  ### Adding a Missing API Suite
    89  
    90  Adding support to a missing suite of API calls will require more than one Pull
    91  Request. However, you can use a single issue for all PRs.
    92  
    93  Examples of issues which track the addition of a missing API suite are:
    94  
    95  * https://github.com/gophercloud/gophercloud/issues/539
    96  * https://github.com/gophercloud/gophercloud/issues/555
    97  * https://github.com/gophercloud/gophercloud/issues/571
    98  * https://github.com/gophercloud/gophercloud/issues/583
    99  * https://github.com/gophercloud/gophercloud/issues/605
   100  
   101  Note how the issue breaks down the implementation by request types (Create,
   102  Update, Delete, Get, List).
   103  
   104  Also note how these issues provide links to the service's Python code. These
   105  links are not required for _issues_, but it's usually a good idea to provide
   106  them, anyway. These links _are required_ for PRs and that will be covered in
   107  detail in a later step of this tutorial.
   108  
   109  ### Adding a Missing OpenStack Project
   110  
   111  These kinds of feature additions are large undertakings. Adding support for
   112  an entire OpenStack project is something the Gophercloud team very much
   113  appreciates, but you should be prepared for several weeks of work and
   114  interaction with the Gophercloud team.
   115  
   116  An example of how to create an issue for an entire project can be seen
   117  here:
   118  
   119  * https://github.com/gophercloud/gophercloud/issues/723
   120  
   121  ---
   122  
   123  With all of the above in mind, proceed to [Step 3](step-03-code-hunting.md) to
   124  learn about Code Hunting.