github.com/thetreep/go-swagger@v0.0.0-20240223100711-35af64f14f01/docs/guidelines/README.md (about)

     1  # Guidelines to maintainers
     2  
     3  A quick guide on how to contribute to `go-swagger` and the other `go-openapi` repos.
     4  
     5  ### Getting started
     6  
     7  Repos follow standard go building and testing rules.
     8  
     9  Cloning `go-swagger`:
    10  ```bash
    11  mkdir -p $GOPATH/src/github.com/go-swagger
    12  cd $GOPATH/src/github.com/go-swagger
    13  git clone https://github.com/thetreep/go-swagger
    14  ```
    15  
    16  All dependencies are available in the checked out `vendor` directory.
    17  
    18  Building and installing go-swagger from source on your system:
    19  ```
    20  go install github.com/thetreep/go-swagger/cmd/swagger
    21  ```
    22  
    23  Running standard unit tests:
    24  ```bash
    25  go test ./...
    26  ```
    27  
    28  More advanced tests are run by CI. See [below](#continuous-integration).
    29  
    30  ### Generally accepted rules for pull requests
    31  
    32  All PR's are welcome and generally accepted (so far, 95% were accepted...).
    33  There are just a few common sense rules to be followed.
    34  
    35  1. PRs which are not ready to merge should be prefixed with `WIP:`
    36  2. Generally, contributors should squash their commits (use `git rebase -i master`)
    37  3. Provide sufficient test coverage with changes
    38  4. Do not bring in uncontrolled dependencies, including from fixtures or examples
    39  5. Use the `fixes #xxx` github feature in PR to automate issue closing
    40  6. Sign-off commits with `git commit -s`. PGP-signed commits with verified signatures are not mandatory (but much appreciated)
    41  7. Use the "draft PR" github feature to draft some work and exercise it against our CI before review
    42  
    43  ### Go environment
    44  
    45  We want to always support the **two most recent go versions**.
    46  
    47  However, we try to avoid introducing breaking changes, especially on the more
    48  stable `go-openapi` repos. We manage this with build tags. Notice the very
    49  important blank line after your build tag comment line.
    50  
    51  Example (from `go-openapi/swag`):
    52  ```go
    53  // +build !go1.8
    54  
    55  package swag
    56  
    57  import "net/url"
    58  
    59  func pathUnescape(path string) (string, error) {
    60  	return url.QueryUnescape(path)
    61  }
    62  ```
    63  
    64  All repos should remain go-gettable (i.e. available with the `go get ./...` command)
    65  and testable with `go test ./...`
    66  
    67  ### Linting
    68  
    69  Check your work with golangci linter:
    70  `go get -u github.com/golangci/golangci-lint/cmd/golangci-lint`
    71  `golangci-lint run --new-from-rev HEAD`
    72  
    73  ### Continuous integration
    74  
    75  All PR's require a review by a team member, whatever the CI engines tell.
    76  
    77  ##### go-swagger/go-swagger
    78  
    79  Enabled CI engines and bots:
    80  - CircleCI (linux)
    81  - Appveyor (windows)
    82  - GolangCI
    83  - Codecov
    84  - DCO (enforce signed-off commits)
    85  - WIP (blocks PRs with title WIP/do not merge, etc...)
    86  
    87  Codecov results are not blocking.
    88  
    89  CI runs description/configuration:
    90  
    91  | CI engine | Test type     | Configuration             | Comment |
    92  |---        |---            |---                        |---      |
    93  | CircleCI  | unit test     | .circleci/config.yml      |         |
    94  |           | build test (1)| ./hack/codegen_nonreg_test.go  | Codegen and build test on many (~ 80) specs in `fixtures/codegen` and `fixtures/bugs``|
    95  |           | build test (2)| ./hack/codegen_nonreg_test.go  | Codegen and build test on (large) specs in fixtures/canary`|
    96  | Appveyor  | unit test     | appveyor.yml              | `go test -v ./...` |
    97  | GolangCI  | linting       | .golangci.yml             | equ. `golangci-lint run` |
    98  | Codecov   | test coverage | -                         | project test coverage and PR diff coverage|
    99  | DCO       | commit signed | -                         | https://probot.github.io/apps/dco|
   100  | WIP       | PR title      | -                         | https://github.com/apps/wip|
   101  
   102  Deprecated engines:
   103  - hound (`.hound.yml`): previous linting checker before we moved to golangCI
   104  
   105  > **NOTE on Appveyor**:
   106  > Appveyor runs our UT on Windows. This makes sure everything works fine
   107  > on this platform as well.
   108  > The peculiarity with this CI is that it does not tolerate output to `stderr`
   109  > from test programs (this is actually a Powershell limitation).
   110  > Therefore, please make sure your UT remain mute on stderr or capture the
   111  > output if you need to assert something from the output.
   112  
   113  The go test program `./hack/codegen_nonreg_test.go` runs on CI with various generation options.
   114  You may run it manually to explore more generation options (expand spec, flatten, etc...).
   115  
   116  ##### Releases
   117  
   118  Released are cut from CircleCI, with a separate workflow to build artifacts, and bake docker images.
   119  
   120  ##### go-openapi repos
   121  
   122  Enabled CI engines:
   123  - Travis (linux)
   124  - GolangCI
   125  - Codecov
   126  - experimental: Appveyor
   127  
   128  | CI engine | Test type     | Configuration             | Comment |
   129  |---        |---            |---                        |---      |
   130  | Travis    | unit test     | .travis.yml               | `go test -v ./...` |
   131  | GolangCI  | linting       | .golangci.yml             | equ. `golangci-lint run` |
   132  
   133  ### Vendoring
   134  
   135  The whole `go-openapi` and `go-swagger` has adopted go modules and no more use vendoring.
   136  
   137  ### Update templates
   138  
   139  `go-swagger` is built with an in-memory image of templates.
   140  
   141  Binary encoded assets are auto-generated from the `generator/templates` directory using `go:embed`.
   142  
   143  > **NOTE**: we are carrying out unit tests on codegen mostly by asserting lines in generated code.
   144  > There is a bunch of test utility functions for this. See `generator/*_test.go`.
   145  >
   146  > If you want to bring in more advanced testing go programs with your fixtures, please tag
   147  > those so they don't affect the `go ./...` command (e.g. with `// +build +integration`).
   148  
   149  ### Updating examples
   150  
   151  Whenever code generation rules change, we feel it is important to maintain
   152  consistency with the generated code provided as examples.
   153  
   154  The script `./hack/regen-samples.sh` does just that.
   155  
   156  Do not forget to update this script when you add a new example.
   157  
   158  ### Writing documentation
   159  
   160  ##### go-swagger/go-swagger
   161  
   162  The `go-swagger` documentation site (`goswagger.io`) is built with GitBooks.
   163  Configuration is in `book.json`. The documents root is in `./docs`
   164  
   165  We systematically copy the repository main `README.md` to `docs/README.md`.
   166  Please make sure links work both from github and gitbook.
   167  
   168  There is also a minimal godoc for goswagger.
   169  
   170  Please make sure new CLI options remain well documented in `./docs/usage` and `./docs/generate`.
   171  
   172  ##### go-openapi repos
   173  
   174  Documentation is limited to the repo's README.md and godoc, published on godoc.org.