diff --git a/.github/ISSUE_TEMPLATE/DESIGN-DOC.yml b/.github/ISSUE_TEMPLATE/DESIGN-DOC.yml index 055577dcc..0460de92d 100644 --- a/.github/ISSUE_TEMPLATE/DESIGN-DOC.yml +++ b/.github/ISSUE_TEMPLATE/DESIGN-DOC.yml @@ -13,8 +13,8 @@ body: Ory is leaning heavily on [Google's design docs process](https://www.industrialempathy.com/posts/design-docs-at-google/) and [Golang Proposals](https://github.com/golang/proposal). - Writing a design doc prior to contributing your change ensures that your ideas are checked with - the community and maintainers. It will save you a lot of time developing things which might need changed + Writing a design doc before contributing your change ensures that your ideas are checked with + the community and maintainers. It will save you a lot of time developing things that might need to be changed after code reviews, and your pull requests will be merged faster. type: markdown - attributes: @@ -64,7 +64,7 @@ body: This section should start with an overview and then go into details. The design doc is the place to write down the trade-offs you made in designing your software. Focus on those trade-offs to produce a useful document with long-term value. That is, given the context (facts), goals and non-goals (requirements), the design doc is the place to suggest solutions and show why a particular solution best satisfies those goals. - The point of writing a document over a more formal medium is to provide the flexibility to express the problem set at hand in an appropriate manner. Because of this, there is no explicit guidance for how to actually describe the design. + The point of writing a document over a more formal medium is to provide the flexibility to express the problem at hand in an appropriate manner. Because of this, there is no explicit guidance on how to actually describe the design. label: "The design" id: design type: textarea @@ -73,21 +73,21 @@ body: - attributes: description: | - If the system under design exposes an API, then sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date. Instead focus on the parts that are relevant to the design and its trade-offs. + If the system under design exposes an API, then sketching out that API is usually a good idea. In most cases, however, one should withstand the temptation to copy-paste formal interface or data definitions into the doc as these are often verbose, contain unnecessary detail and quickly get out of date. Instead, focus on the parts that are relevant to the design and its trade-offs. label: "APIs" id: apis type: textarea - attributes: description: | - Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead focus on the parts that are relevant to the design and its trade-offs. + Systems that store data should likely discuss how and in what rough form this happens. Similar to the advice on APIs, and for the same reasons, copy-pasting complete schema definitions should be avoided. Instead, focus on the parts that are relevant to the design and its trade-offs. label: "Data storage" id: persistence type: textarea - attributes: description: | - Design docs should rarely contain code, or pseudo-code except in situations where novel algorithms are described. As appropriate, link to prototypes that show the implementability of the design. + Design docs should rarely contain code, or pseudo-code except in situations where novel algorithms are described. As appropriate, link to prototypes that show the feasibility of the design. label: "Code and pseudo-code" id: pseudocode type: textarea @@ -98,9 +98,9 @@ body: On one end of the extreme is the “greenfield software project”, where all we know are the goals, and the solution can be whatever makes the most sense. Such a document may be wide-ranging, but it also needs to quickly define a set of rules that allow zooming in on a manageable set of solutions. - On the other end are systems where the possible solutions are very well defined, but it isn’t at all obvious how they could even be combined to achieve the goals. This may be a legacy system that is difficult to change and wasn’t designed to do what you want it to do or a library design that needs to operate within the constraints of the host programming language. + On the other end are systems where the possible solutions are very well defined, but it isn't at all obvious how they could even be combined to achieve the goals. This may be a legacy system that is difficult to change and wasn't designed to do what you want it to do or a library design that needs to operate within the constraints of the host programming language. - In this situation you may be able to enumerate all the things you can do relatively easily, but you need to creatively put those things together to achieve the goals. There may be multiple solutions, and none of them are really great, and hence such a document should focus on selecting the best way given all identified trade-offs. + In this situation, you may be able to enumerate all the things you can do relatively easily, but you need to creatively put those things together to achieve the goals. There may be multiple solutions, and none of them are great, and hence such a document should focus on selecting the best way given all identified trade-offs. label: "Degree of constraint" id: constrait type: textarea @@ -109,7 +109,7 @@ body: description: | This section lists alternative designs that would have reasonably achieved similar outcomes. The focus should be on the trade-offs that each respective design makes and how those trade-offs led to the decision to select the design that is the primary topic of the document. - While it is fine to be succinct about solution that ended up not being selected, this section is one of the most important ones as it shows very explicitly why the selected solution is the best given the project goals and how other solutions, that the reader may be wondering about, introduce trade-offs that are less desirable given the goals. + While it is fine to be succinct about a solution that ended up not being selected, this section is one of the most important ones as it shows very explicitly why the selected solution is the best given the project goals and how other solutions, that the reader may be wondering about, introduce trade-offs that are less desirable given the goals. label: Alternatives considered id: alternatives diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e77af3265..079629708 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,7 +2,7 @@ Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request. This text will be included in the changelog. If applicable, include links to documentation or pieces of code. -If your change includes breaking changes please add a codeblock documenting the breaking change: +If your change includes breaking changes please add a code block documenting the breaking change: ``` BREAKING CHANGES: This patch changes the behavior of configuration item `foo` to do bar. To keep the existing @@ -23,7 +23,7 @@ If this pull request Pull requests introducing new features, which do not have a design document linked are more likely to be rejected and take on average 2-8 weeks longer to get merged. -You can discuss changes with maintainers either in the Github Discusssions in this repository or +You can discuss changes with maintainers either in the Github Discussions in this repository or join the [Ory Chat](https://www.ory.sh/chat). --> @@ -39,9 +39,9 @@ them, don't hesitate to ask. We're here to help! This is simply a reminder of wh - [ ] I have read the [security policy](../security/policy). - [ ] I confirm that this pull request does not address a security vulnerability. If this pull request addresses a security vulnerability, - I confirm that I got green light (please contact [security@ory.sh](mailto:security@ory.sh)) from the maintainers to push the changes. + I confirm that I got approval (please contact [security@ory.sh](mailto:security@ory.sh)) from the maintainers to push the changes. - [ ] I have added tests that prove my fix is effective or that my feature works. -- [ ] I have added necessary documentation within the code base (if appropriate). +- [ ] I have added the necessary documentation within the code base (if appropriate). ## Further comments diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index eb36db174..666299c49 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -15,12 +15,12 @@ jobs: stale-issue-message: | Hello contributors! - I am marking this issue as stale as it has not received any engagement from the community or maintainers a year. That does not imply that the issue has no merit! If you feel strongly about this issue + I am marking this issue as stale as it has not received any engagement from the community or maintainers for a year. That does not imply that the issue has no merit! If you feel strongly about this issue - open a PR referencing and resolving the issue; - - leave a comment on it and discuss ideas how you could contribute towards resolving it; + - leave a comment on it and discuss ideas on how you could contribute towards resolving it; - leave a comment and describe in detail why this issue is critical for your use case; - - open a new issue with updated details and a plan on resolving the issue. + - open a new issue with updated details and a plan for resolving the issue. Throughout its lifetime, Ory has received over 10.000 issues and PRs. To sustain that growth, we need to prioritize and focus on issues that are important to the community. A good indication of importance, and thus priority, is activity on a topic. @@ -30,7 +30,7 @@ jobs: The motivation for this automation is to help prioritize issues in the backlog and not ignore, reject, or belittle anyone. - If this issue was marked as stale erroneous you can exempt it by adding the `backlog` label, assigning someone, or setting a milestone for it. + If this issue was marked as stale erroneously you can exempt it by adding the `backlog` label, assigning someone, or setting a milestone for it. Thank you for your understanding and to anyone who participated in the conversation! And as written above, please do participate in the conversation if this topic is important to you! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3b11e479..18fbb6862 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,19 +31,19 @@ https://github.com/ory/meta/blob/master/templates/repository/common/CONTRIBUTING _Please note_: We take Ory Fosite's security and our users' trust very seriously. If you believe you have found a security issue in Ory Fosite, -please disclose by contacting us at security@ory.sh. +please disclose it by contacting us at security@ory.sh. There are many ways in which you can contribute. The goal of this document is to provide a high-level overview of how you can get involved in Ory. As a potential contributor, your changes and ideas are welcome at any hour of -the day or night, weekdays, weekends, and holidays. Please do not ever hesitate -to ask a question or send a pull request. +the day or night, on weekdays, weekends, and holidays. Please do not ever +hesitate to ask a question or send a pull request. If you are unsure, just ask or submit the issue or pull request anyways. You won't be yelled at for giving it your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of -contributions, and don't want a wall of rules to get in the way of that. +contributions and don't want a wall of rules to get in the way of that. That said, if you want to ensure that a pull request is likely to be merged, talk to us! You can find out our thoughts and ensure that your contribution @@ -93,8 +93,8 @@ to help out: look at discussions in the forum and take part in community events. More info on this in [Communication](#communication). -- **Answer discussions.** There are at all times a number of unanswered - discussions on GitHub, you can see an +- **Answer discussions.** At all times, there are several unanswered discussions + on GitHub. You can see an [overview here](https://github.com/discussions?discussions_q=is%3Aunanswered+org%3Aory+sort%3Aupdated-desc). If you think you know an answer or can provide some information that might help, please share it! Bonus: You get GitHub achievements for answered @@ -103,13 +103,13 @@ to help out: - **Help with open issues.** We have a lot of open issues for Ory Fosite and some of them may lack necessary information, some are duplicates of older issues. You can help out by guiding people through the process of filling out - the issue template, asking for clarifying information, or pointing them to + the issue template, asking for clarifying information or pointing them to existing issues that match their description of the problem. - **Review documentation changes.** Most documentation just needs a review for proper spelling and grammar. If you think a document can be improved in any way, feel free to hit the `edit` button at the top of the page. More info on - contributing to documentation [here](#contribute-documentation). + contributing to the documentation [here](#contribute-documentation). - **Help with tests.** Pull requests may lack proper tests or test plans. These are needed for the change to be implemented safely. @@ -122,7 +122,7 @@ questions, discuss bugs and feature requests, talk to other users of Ory, etc. Check out [Ory Fosite Discussions](https://github.com/orgs/ory/discussions). This is a great place for in-depth discussions and lots of code examples, logs and similar data. -You can also join our community calls, if you want to speak to the Ory team +You can also join our community calls if you want to speak to the Ory team directly or ask some questions. You can find more info and participate in [Slack](https://www.ory.sh/chat) in the #community-call channel. @@ -130,12 +130,12 @@ If you want to receive regular notifications about updates to Ory Fosite, consider joining the mailing list. We will _only_ send you vital information on the projects that you are interested in. -Also [follow us on twitter](https://twitter.com/orycorp). +Also, [follow us on Twitter](https://twitter.com/orycorp). ## Contribute examples -One of the most impactful ways to make a contribution is adding examples. You -can find an overview of examples using Ory services in the +One of the most impactful ways to contribute is by adding examples. You can find +an overview of examples using Ory services on the [documentation examples page](https://www.ory.sh/docs/examples). Source code for examples can be found in most cases in the [ory/examples](https://github.com/ory/examples) repository. @@ -147,7 +147,7 @@ describe your example before you start working on it. We would love to provide guidance to make for a pleasant contribution experience. Go through this checklist to contribute an example: -1. Create a github issue proposing a new example and make sure it's different +1. Create a GitHub issue proposing a new example and make sure it's different from an existing one. 1. Fork the repo and create a feature branch off of `master` so that changes do not get mixed up. @@ -196,13 +196,14 @@ us the rights to use your contribution. You can see the Apache 2.0 license under which our projects are published [here](https://github.com/ory/meta/blob/master/LICENSE). -When pull requests fail testing, authors are expected to update their pull -requests to address the failures until the tests pass. +When pull requests fail the automated testing stages (for example unit or E2E +tests), authors are expected to update their pull requests to address the +failures until the tests pass. Pull requests eligible for review 1. follow the repository's code formatting conventions; -2. include tests which prove that the change works as intended and does not add +2. include tests that prove that the change works as intended and does not add regressions; 3. document the changes in the code and/or the project's documentation; 4. pass the CI pipeline; diff --git a/SECURITY.md b/SECURITY.md index 70f1ef4dd..52387a3a8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -21,8 +21,8 @@ https://github.com/ory/meta/blob/master/templates/repository/SECURITY.md ## Supported Versions -We release patches for security vulnerabilities. Which versions are eligible -receiving such patches depend on the CVSS v3.0 Rating: +We release patches for security vulnerabilities. Which versions are eligible for +receiving such patches depends on the CVSS v3.0 Rating: | CVSS v3.0 | Supported Versions | | --------- | ----------------------------------------- |