github.com/huaweicloud/golangsdk@v0.0.0-20210831081626-d823fe11ceba/STYLEGUIDE.md (about)

     1  
     2  ## On Pull Requests
     3  
     4  - Please make sure to read our [contributing guide](/.github/CONTRIBUTING.md).
     5  
     6  - Before you start a PR there needs to be a Github issue and a discussion about it
     7    on that issue with a core contributor, even if it's just a 'SGTM'.
     8  
     9  - A PR's description must reference the issue it closes with a `For <ISSUE NUMBER>` (e.g. For #293).
    10  
    11  - A PR's description must contain link(s) to the line(s) in the OpenStack
    12    source code (on Github) that prove(s) the PR code to be valid. Links to documentation
    13    are not good enough. The link(s) should be to a non-`master` branch. For example,
    14    a pull request implementing the creation of a Neutron v2 subnet might put the
    15    following link in the description:
    16  
    17    https://github.com/openstack/neutron/blob/stable/mitaka/neutron/api/v2/attributes.py#L749
    18  
    19    From that link, a reviewer (or user) can verify the fields in the request/response
    20    objects in the PR.
    21  
    22  - A PR that is in-progress should have `[wip]` in front of the PR's title. When
    23    ready for review, remove the `[wip]` and ping a core contributor with an `@`.
    24  
    25  - Forcing PRs to be small can have the effect of users submitting PRs in a hierarchical chain, with
    26    one depending on the next. If a PR depends on another one, it should have a [Pending #PRNUM]
    27    prefix in the PR title. In addition, it will be the PR submitter's responsibility to remove the
    28    [Pending #PRNUM] tag once the PR has been updated with the merged, dependent PR. That will
    29    let reviewers know it is ready to review.
    30  
    31  - A PR should be small. Even if you intend on implementing an entire
    32    service, a PR should only be one route of that service
    33    (e.g. create server or get server, but not both).
    34  
    35  - Unless explicitly asked, do not squash commits in the middle of a review; only
    36    append. It makes it difficult for the reviewer to see what's changed from one
    37    review to the next.
    38  
    39  - See [#583](https://github.com/huaweicloud/golangsdk/issues/583) as an example of a
    40    well-formatted issue which contains all relevant information we need to review and approve.
    41  
    42  ## On Code
    43  
    44  - In re design: follow as closely as is reasonable the code already in the library.
    45    Most operations (e.g. create, delete) admit the same design.
    46  
    47  - Unit tests and acceptance (integration) tests must be written to cover each PR.
    48    Tests for operations with several options (e.g. list, create) should include all
    49    the options in the tests. This will allow users to verify an operation on their
    50    own infrastructure and see an example of usage.
    51  
    52  - If in doubt, ask in-line on the PR.
    53  
    54  ### File Structure
    55  
    56  - The following should be used in most cases:
    57  
    58    - `requests.go`: contains all the functions that make HTTP requests and the
    59      types associated with the HTTP request (parameters for URL, body, etc)
    60    - `results.go`: contains all the response objects and their methods
    61    - `urls.go`: contains the endpoints to which the requests are made
    62  
    63  ### Naming
    64  
    65  - For methods on a type in `results.go`, the receiver should be named `r` and the
    66    variable into which it will be unmarshalled `s`.
    67  
    68  - Functions in `requests.go`, with the exception of functions that return a
    69    `pagination.Pager`, should be named returns of the name `r`.
    70  
    71  - Functions in `requests.go` that accept request bodies should accept as their
    72    last parameter an `interface` named `<Action>OptsBuilder` (eg `CreateOptsBuilder`).
    73    This `interface` should have at the least a method named `To<Resource><Action>Map`
    74    (eg `ToPortCreateMap`).
    75  
    76  - Functions in `requests.go` that accept query strings should accept as their
    77    last parameter an `interface` named `<Action>OptsBuilder` (eg `ListOptsBuilder`).
    78    This `interface` should have at the least a method named `To<Resource><Action>Query`
    79    (eg `ToServerListQuery`).