github.com/gophercloud/gophercloud@v1.11.0/docs/contributor-tutorial/step-03-code-hunting.md (about)

     1  Step 3: Code Hunting
     2  ====================
     3  
     4  If you plan to submit a feature or bug fix to Gophercloud, you must be
     5  able to prove your code correctly works with the OpenStack service in
     6  question.
     7  
     8  Let's use the following issue as an example:
     9  [https://github.com/gophercloud/gophercloud/issues/621](https://github.com/gophercloud/gophercloud/issues/621).
    10  In this issue, there's a request being made to add support for
    11  `availability_zone_hints` to the `networking/v2/networks` package.
    12  Meaning, we want to change:
    13  
    14  ```go
    15  type Network struct {
    16  	ID           string   `json:"id"`
    17  	Name         string   `json:"name"`
    18  	AdminStateUp bool     `json:"admin_state_up"`
    19  	Status       string   `json:"status"`
    20  	Subnets      []string `json:"subnets"`
    21  	TenantID     string   `json:"tenant_id"`
    22  	Shared       bool     `json:"shared"`
    23  }
    24  ```
    25  
    26  to look like
    27  
    28  ```go
    29  type Network struct {
    30  	ID                    string   `json:"id"`
    31  	Name                  string   `json:"name"`
    32  	AdminStateUp          bool     `json:"admin_state_up"`
    33  	Status                string   `json:"status"`
    34  	Subnets               []string `json:"subnets"`
    35  	TenantID              string   `json:"tenant_id"`
    36  	Shared                bool     `json:"shared"`
    37  
    38  	AvailabilityZoneHints []string `json:"availability_zone_hints"`
    39  }
    40  ```
    41  
    42  We need to be sure that `availability_zone_hints` is a field which really does
    43  exist in the OpenStack Neutron project and it's not a field which was added as
    44  a customization to a single OpenStack cloud.
    45  
    46  In addition, we need to ensure that `availability_zone_hints` is really a
    47  `[]string` and not a different kind of type.
    48  
    49  One way of verifying this is through the [OpenStack API reference
    50  documentation](https://developer.openstack.org/api-ref/network/v2/).
    51  However, the API docs might either be incorrect or they might not provide all of
    52  the details we need to know in order to ensure this field is added correctly.
    53  
    54  > Note: when we say the API docs might be incorrect, we are _not_ implying
    55  > that the API docs aren't useful or that the contributors who work on the API
    56  > docs are wrong. OpenStack moves fast. Typos happen. Forgetting to update
    57  > documentation happens.
    58  
    59  Since the OpenStack service itself correctly accepts and processes the fields,
    60  the best source of information on how the field works is in the service code
    61  itself.
    62  
    63  Continuing on with using #621 as an example, we can find the definition of
    64  `availability_zone_hints` in the following piece of code:
    65  
    66  https://github.com/openstack/neutron/blob/8e9959725eda4063a318b4ba6af1e3494cad9e35/neutron/objects/network.py#L191
    67  
    68  The above code confirms that `availability_zone_hints` is indeed part of the
    69  `Network` object and that its type is a list of strings (`[]string`).
    70  
    71  This example is a best-case situation: the code is relatively easy to find
    72  and it's simple to understand. However, there will be times when proving the
    73  implementation in the service code is difficult. Make no mistake, this is _not_
    74  fun work. This can sometimes be more difficult than writing the actual patch
    75  for Gophercloud. However, this is an essential step to ensuring the feature
    76  or bug fix is correctly added to Gophercloud.
    77  
    78  Examples of good code hunting can be seen here:
    79  
    80  * https://github.com/gophercloud/gophercloud/issues/539
    81  * https://github.com/gophercloud/gophercloud/issues/555
    82  * https://github.com/gophercloud/gophercloud/issues/571
    83  * https://github.com/gophercloud/gophercloud/issues/583
    84  * https://github.com/gophercloud/gophercloud/issues/605
    85  
    86  Code Hunting Tips
    87  -----------------
    88  
    89  OpenStack projects differ from one to another. Code is organized in different
    90  ways. However, the following tips should be useful across all projects.
    91  
    92  * The logic which implements Create and Delete actions is usually either located
    93    in the "model" or "controller" portion of the code.
    94  
    95  * Use Github's search box to search for the exact field you're working on.
    96    Review all results to gain a good understanding of everywhere the field is
    97    used.
    98  
    99  * When adding a field, look for an object model or a schema of some sort.
   100  
   101  ---
   102  
   103  Proceed to [Step 4](step-04-acceptance-testing.md) to learn about Acceptance
   104  Testing.