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