github.com/authzed/spicedb@v1.32.1-0.20240520085336-ebda56537386/CONTRIBUTING.md (about)

     1  # How to contribute
     2  
     3  ## Communication
     4  
     5  - Bug Reports & Feature Requests: [GitHub Issues]
     6  - Questions: [GitHub Discussions] or [Discord]
     7  
     8  All communication in these forums abides by our [Code of Conduct].
     9  
    10  [GitHub Issues]: https://github.com/authzed/spicedb/issues
    11  [Code of Conduct]: CODE-OF-CONDUCT.md
    12  [Github Discussions]: https://github.com/orgs/authzed/discussions/new?category=q-a
    13  [Discord]: https://authzed.com/discord
    14  
    15  ## Creating issues
    16  
    17  If any part of the project has a bug or documentation mistakes, please let us know by opening an issue.
    18  All bugs and mistakes are considered very seriously, regardless of complexity.
    19  
    20  Before creating an issue, please check that an issue reporting the same problem does not already exist.
    21  To make the issue accurate and easy to understand, please try to create issues that are:
    22  
    23  - Unique -- do not duplicate existing bug report.
    24    Duplicate bug reports will be closed.
    25  - Specific -- include as much details as possible: which version, what environment, what configuration, etc.
    26  - Reproducible -- include the steps to reproduce the problem.
    27    Some issues might be hard to reproduce, so please do your best to include the steps that might lead to the problem.
    28  - Isolated -- try to isolate and reproduce the bug with minimum dependencies.
    29    It would significantly slow down the speed to fix a bug if too many dependencies are involved in a bug report.
    30    Debugging external systems that rely on this project is out of scope, but guidance or help using the project itself is fine.
    31  - Scoped -- one bug per report.
    32    Do not follow up with another bug inside one report.
    33  
    34  It may be worthwhile to read [Elika Etemad’s article on filing good bug reports][filing-good-bugs] before creating a bug report.
    35  
    36  Maintainers might ask for further information to resolve an issue.
    37  
    38  [filing-good-bugs]: http://fantasai.inkedblade.net/style/talks/filing-good-bugs/
    39  
    40  ## Finding issues
    41  
    42  You can find issues by priority: [Urgent], [High], [Medium], [Low], [Maybe].
    43  There are also [good first issues].
    44  
    45  [Urgent]: https://github.com/authzed/spicedb/labels/priority%2F0%20urgent
    46  [High]: https://github.com/authzed/spicedb/labels/priority%2F1%20high
    47  [Medium]: https://github.com/authzed/spicedb/labels/priority%2F2%20medium
    48  [Low]: https://github.com/authzed/spicedb/labels/priority%2F3%20low
    49  [Maybe]: https://github.com/authzed/spicedb/labels/priority%2F4%20maybe
    50  [good first issues]: https://github.com/authzed/spicedb/labels/hint%2Fgood%20first%20issue
    51  
    52  ## Contribution flow
    53  
    54  This is a rough outline of what a contributor's workflow looks like:
    55  
    56  - Create an issue
    57  - Fork the project
    58  - Create a [feature branch]
    59  - Push changes to your branch
    60  - Submit a pull request
    61  - Respond to feedback from project maintainers
    62  - Rebase to squash related and fixup commits
    63  - Get LGTM from reviewer(s)
    64  - Merge with a merge commit
    65  
    66  Creating new issues is one of the best ways to contribute.
    67  You have no obligation to offer a solution or code to fix an issue that you open.
    68  If you do decide to try and contribute something, please submit an issue first so that a discussion can occur to avoid any wasted efforts.
    69  
    70  [feature branch]: https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow
    71  
    72  ## Legal requirements
    73  
    74  In order to protect the project, all contributors are required to sign our [Contributor License Agreement][cla] before their contribution is accepted.
    75  
    76  The signing process has been automated by [CLA Assistant][cla-assistant] during the Pull Request review process and only requires responding with a comment acknowledging the agreement.
    77  
    78  [cla]: https://github.com/authzed/cla/blob/main/v1/icla.md
    79  [cla-assistant]: https://github.com/cla-assistant/cla-assistant
    80  
    81  ## Common tasks
    82  
    83  We use [mage](https://magefile.org/#installation) to run common tasks in the project.
    84  Mage can be installed system-wide, or can be run with no installation with `go run mage.go`
    85  
    86  ### Testing
    87  
    88  In order to build and test the project, the [latest stable version of Go] and knowledge of a [working Go environment] are required.
    89  
    90  [latest stable version of Go]: https://golang.org/dl
    91  [working Go environment]: https://golang.org/doc/code.html
    92  
    93  ```sh
    94  mage test:unit
    95  ```
    96  
    97  To run integration tests (for example when testing datastores):
    98  
    99  ```sh
   100  mage test:integration
   101  ```
   102  
   103  Run `mage` or `mage -l` for a full list of test suites.
   104  
   105  ### Linting
   106  
   107  SpiceDB uses several linters to maintain code and docs quality.
   108  
   109  Run them with:
   110  
   111  ```sh
   112  mage lint:all
   113  ```
   114  
   115  See `mage -l` to run specific linters.
   116  
   117  ### Adding dependencies
   118  
   119  This project does not use anything other than the standard [Go modules] toolchain for managing dependencies.
   120  
   121  [Go modules]: https://golang.org/ref/mod
   122  
   123  ```sh
   124  go get github.com/org/newdependency@version
   125  ```
   126  
   127  Continuous integration enforces that `go mod tidy` has been run.
   128  
   129  `mage deps:tidy` can be used to tidy all go modules in the project at once.
   130  
   131  ### Updating generated Protobuf code
   132  
   133  All [Protobuf] code is managed using [buf].
   134  
   135  To regenerate the protos:
   136  
   137  ```sh
   138  mage gen:proto
   139  ```
   140  
   141  [Protobuf]: https://developers.google.com/protocol-buffers/
   142  [buf]: https://docs.buf.build/installation