github.com/chnsz/golangsdk@v0.0.0-20240506093406-85a3fbfa605b/STYLEGUIDE.md (about)

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