1<!--
2
3Thank you for contributing changes to this document! Because we use a central repository
4to synchronize this file across all our repositories, make sure to make your edits
5in the correct file, which you can find here:
6
7https://github.com/ory/meta/blob/master/templates/repository/common/CONTRIBUTING.md
8
9-->
10
11# Contributing to ORY X
12
13<!-- START doctoc generated TOC please keep comment here to allow auto update -->
14<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
15
16- [Introduction](#introduction)
17- [FAQ](#faq)
18- [How can I contribute?](#how-can-i-contribute)
19- [Communication](#communication)
20- [Contributing Code](#contributing-code)
21- [Documentation](#documentation)
22- [Disclosing vulnerabilities](#disclosing-vulnerabilities)
23- [Code Style](#code-style)
24- [Pull request procedure](#pull-request-procedure)
25 - [Working with Forks](#working-with-forks)
26- [Conduct](#conduct)
27
28<!-- END doctoc generated TOC please keep comment here to allow auto update -->
29
30## Introduction
31
32There are many ways in which you can contribute, beyond writing code. The goal
33of this document is to provide a high-level overview of how you can get
34involved.
35
36_Please note_: We take ORY X's security and our users' trust very
37seriously. If you believe you have found a security issue in ORY X,
38please responsibly disclose by contacting us at security@ory.sh.
39
40First: As a potential contributor, your changes and ideas are welcome at any
41hour of the day or night, weekdays, weekends, and holidays. Please do not ever
42hesitate to ask a question or send a pull request.
43
44If you are unsure, just ask or submit the issue or pull request anyways. You
45won't be yelled at for giving it your best effort. The worst that can happen is
46that you'll be politely asked to change something. We appreciate any sort of
47contributions, and don't want a wall of rules to get in the way of that.
48
49That said, if you want to ensure that a pull request is likely to be merged,
50talk to us! You can find out our thoughts and ensure that your contribution
51won't clash or be obviated by ORY
52X's normal direction. A great way to
53do this is via
54[ORY X Discussions](https://github.com/ory/meta/discussions)
55or the [ORY Chat](https://www.ory.sh/chat).
56
57## FAQ
58
59- I am new to the community. Where can I find the
60 [ORY Community Code of Conduct?](https://github.com/ory/x/blob/master/CODE_OF_CONDUCT.md)
61
62- I have a question. Where can I get
63 [answers to questions regarding ORY X?](#communication)
64
65- I would like to contribute but I am not sure how. Are there
66 [easy ways to contribute?](#how-can-i-contribute)
67 [Or good first issues?](https://github.com/search?l=&o=desc&q=label%3A%22help+wanted%22+label%3A%22good+first+issue%22+is%3Aopen+user%3Aory+user%3Aory-corp&s=updated&type=Issues)
68
69- I want to talk to other ORY X users.
70 [How can I become a part of the community?](#communication)
71
72- I would like to know what I am agreeing to when I contribute to ORY
73 X.
74 Does ORY have
75 [a Contributors License Agreement?](https://cla-assistant.io/ory/x)
76
77- I would like updates about new versions of ORY X.
78 [How are new releases announced?](https://ory.us10.list-manage.com/subscribe?u=ffb1a878e4ec6c0ed312a3480&id=f605a41b53)
79
80## How can I contribute?
81
82If you want to start contributing code right away, we have a
83[list of good first issues](https://github.com/ory/x/labels/good%20first%20issue).
84
85There are many other ways you can contribute without writing any code. Here are
86a few things you can do to help out:
87
88- **Give us a star.** It may not seem like much, but it really makes a
89 difference. This is something that everyone can do to help out ORY X.
90 Github stars help the project gain visibility and stand out.
91
92- **Join the community.** Sometimes helping people can be as easy as listening
93 to their problems and offering a different perspective. Join our Slack, have a
94 look at discussions in the forum and take part in our weekly hangout. More
95 info on this in [Communication](#communication).
96
97- **Helping with open issues.** We have a lot of open issues for ORY X
98 and some of them may lack necessary information, some are duplicates of older
99 issues. You can help out by guiding people through the process of filling out
100 the issue template, asking for clarifying information, or pointing them to
101 existing issues that match their description of the problem.
102
103- **Reviewing documentation changes.** Most documentation just needs a review
104 for proper spelling and grammar. If you think a document can be improved in
105 any way, feel free to hit the `edit` button at the top of the page. More info
106 on contributing to documentation here.
107
108- **Help with tests.** Some pull requests may lack proper tests or test plans.
109 These are needed for the change to be implemented safely.
110
111## Communication
112
113We use [Slack](https://www.ory.sh/chat). You are welcome to drop in and ask
114questions, discuss bugs and feature requests, talk to other users of ORY, etc.
115
116Check out [ORY X Discussions](https://github.com/ory/meta/discussions). This is a great place for
117in-depth discussions and lots of code examples, logs and similar data.
118
119You can also join our community hangout, if you want to speak to the ORY team
120directly or ask some questions. You can find more info on the hangouts in
121[Slack](https://www.ory.sh/chat).
122
123If you want to receive regular notifications about updates to ORY X,
124consider joining the mailing list. We will _only_ send you vital information on
125the projects that you are interested in.
126
127Also [follow us on twitter](https://twitter.com/orycorp).
128
129## Contributing Code
130
131Unless you are fixing a known bug, we **strongly** recommend discussing it with
132the core team via a GitHub issue or [in our chat](https://www.ory.sh/chat)
133before getting started to ensure your work is consistent with ORY X's
134roadmap and architecture.
135
136All contributions are made via pull request. Note that **all patches from all
137contributors get reviewed**. After a pull request is made other contributors
138will offer feedback, and if the patch passes review a maintainer will accept it
139with a comment. When pull requests fail testing, authors are expected to update
140their pull requests to address the failures until the tests pass and the pull
141request merges successfully. Look here for more info on the
142[Pull request procedure](#pull-request-procedure).
143
144At least one review from a maintainer is required for all patches (even patches
145from maintainers).
146
147Before your contributions can be merged you need to sign our
148[Contributor License Agreement](https://cla-assistant.io/ory/x).
149
150This agreement defines the terms under which your code is contributed to ORY.
151More specifically it declares that you have the right to, and actually do, grant
152us the rights to use your contribution. You can see the Apache 2.0 license under
153which our projects are published
154[here](https://github.com/ory/meta/blob/master/LICENSE).
155
156Reviewers should leave a "LGTM" comment once they are satisfied with the patch.
157If the patch was submitted by a maintainer with write access, the pull request
158should be merged by the submitter after review.
159
160## Documentation
161
162Please provide documentation when changing, removing, or adding features.
163Documentation resides in the project's
164[docs](https://github.com/ory/x/tree/master/docs) folder. Generate API and
165configuration reference documentation using `cd docs; npm run gen`.
166
167For further instructions please head over to
168[docs/README.md](https://github.com/ory/x/blob/master/README.md).
169
170## Disclosing vulnerabilities
171
172Please disclose vulnerabilities exclusively to
173[security@ory.sh](mailto:security@ory.sh). Do not use GitHub issues.
174
175## Code Style
176
177Please follow these guidelines when formatting source code:
178
179- Go code should match the output of `gofmt -s` and pass `golangci-lint run`.
180- NodeJS and JavaScript code should be prettified using `npm run format` where
181 appropriate.
182
183## Pull request procedure
184
185To make a pull request, you will need a GitHub account; if you are unclear on
186this process, see GitHub's documentation on
187[forking](https://help.github.com/articles/fork-a-repo) and
188[pull requests](https://help.github.com/articles/using-pull-requests). Pull
189requests should be targeted at the `master` branch. Before creating a pull
190request, go through this checklist:
191
1921. Create a feature branch off of `master` so that changes do not get mixed up.
1931. [Rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) your local
194 changes against the `master` branch.
1951. Run the full project test suite with the `go test ./...` (or equivalent)
196 command and confirm that it passes.
1971. Run `gofmt -s` (if the project is written in Go).
1981. Ensure that each commit has a subsystem prefix (ex: `controller:`).
199
200Pull requests will be treated as "review requests," and maintainers will give
201feedback on the style and substance of the patch.
202
203Normally, all pull requests must include tests that test your change.
204Occasionally, a change will be very difficult to test for. In those cases,
205please include a note in your commit message explaining why.
206
207### Working with Forks
208
209```
210# First you clone the original repository
211git clone git@github.com:ory/ory/x.git
212
213# Next you add a git remote that is your fork:
214git remote add fork git@github.com:<YOUR-GITHUB-USERNAME-HERE>/ory/x.git
215
216# Next you fetch the latest changes from origin for master:
217git fetch origin
218git checkout master
219git pull --rebase
220
221# Next you create a new feature branch off of master:
222git checkout my-feature-branch
223
224# Now you do your work and commit your changes:
225git add -A
226git commit -a -m "fix: this is the subject line" -m "This is the body line. Closes #123"
227
228# And the last step is pushing this to your fork
229git push -u fork my-feature-branch
230```
231
232Now go to the project's GitHub Pull Request page and click "New pull request"
233
234## Conduct
235
236Whether you are a regular contributor or a newcomer, we care about making this
237community a safe place for you and we've got your back.
238
239- We are committed to providing a friendly, safe and welcoming environment for
240 all, regardless of gender, sexual orientation, disability, ethnicity,
241 religion, or similar personal characteristic.
242- Please avoid using nicknames that might detract from a friendly, safe and
243 welcoming environment for all.
244- Be kind and courteous. There is no need to be mean or rude.
245- We will exclude you from interaction if you insult, demean or harass anyone.
246 In particular, we do not tolerate behavior that excludes people in socially
247 marginalized groups.
248- Private harassment is also unacceptable. No matter who you are, if you feel
249 you have been or are being harassed or made uncomfortable by a community
250 member, please contact one of the channel ops or a member of the ORY X
251 core team immediately.
252- Likewise any spamming, trolling, flaming, baiting or other attention-stealing
253 behaviour is not welcome.
254
255We welcome discussion about creating a welcoming, safe, and productive
256environment for the community. If you have any questions, feedback, or concerns
257[please let us know](https://www.ory.sh/chat).
View as plain text