diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..36b1cb7b31b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# How to contribute + +First, thanks for taking the time to contribute to our project! There are many ways you can help out. + +### Questions + +If you have a question that needs an answer, [create an issue](https://help.github.com/articles/creating-an-issue/), and label it as a question. +Another option is to initiate a [discussion](https://github.com/AthenZ/athenz/discussions). + +### Issues for bugs or feature requests + +If you encounter any bugs in the code, or want to request a new feature or enhancement, please [create an issue](https://help.github.com/articles/creating-an-issue/) to report it. Kindly add a label to indicate what type of issue it is. + +### Contribute Code + +We ask that before contributing, please make the effort to coordinate with the maintainers of the project before submitting large or high +impact PRs. This will prevent you from doing extra work that may or may not be merged. + +While pull requests are the methodology for submitting changes to code, changes are much more likely to be accepted if they are accompanied by +additional engineering work. While we don't define this explicitly, most of these goals are accomplished through communication of the design +goals and subsequent solutions. Often times, it helps to first state the problem before presenting solutions. + +Typically, the best methods of accomplishing this are to submit an issue, stating the problem. This issue can include a problem statement and a +checklist with requirements. If solutions are proposed, alternatives should be listed and eliminated. Even if the criteria for elimination of +a solution is frivolous, say so. + +Make sure that new tests are added for bugs in order to catch regressions and tests with new features to exercise the new functionality that +is added. + +***Creating a Pull Request*** + +Please follow [best practices](https://github.com/trein/dev-best-practices/wiki/Git-Commit-Best-Practices) for creating git commits. + +When your code is ready to be submitted, [submit a pull request](https://help.github.com/articles/creating-a-pull-request/) to begin the code review process. + +## Sign your work + +The sign-off is a simple line at the end of the explanation for the patch. Your +signature certifies that you wrote the patch or otherwise have the right to pass +it on as an open-source patch. The rules are pretty simple: if you can certify +the below (from [developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA 94129 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +Then you just add a line to every git commit message: + + Signed-off-by: Joe Smith + +Use your real name (sorry, no pseudonyms or anonymous contributions.) + +If you set your `user.name` and `user.email` git configs, you can sign your +commit automatically with `git commit -s`. \ No newline at end of file diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 00000000000..692686bc092 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,124 @@ +# Athenz Governance + +As a CNCF member project, we abide by the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). + +For specific guidance on practical contribution steps for any Athenz sub-project please see our [CONTRIBUTING.md](CONTRIBUTING.md) guide. + +## Maintainership + +There are different types of maintainers, with different responsibilities, but all maintainers have 3 things in common: + +1) They share responsibility in the project's success. +2) They have made a long-term, recurring time investment to improve the project. +3) They spend that time doing whatever needs to be done, not necessarily what is the most interesting or fun. + +## Reviewers + +A reviewer is a core role within the project. They share in reviewing issues and pull requests, and their **thumbs up** counts towards +the required **thumbs up** count to merge a code change into the project. + +Reviewers may or may not have write access. Being a reviewer is key to becoming a maintainer. + +## Adding maintainers + +Maintainers are first and foremost contributors that have shown they are committed to the long term success of a project. +Contributors wanting to become maintainers are expected to be deeply involved in contributing code, pull request review, and triage of issues +in the project for more than three months. + +Just contributing does not make you a maintainer, it is about building trust with the current maintainers of the project and being a person +that they can depend on and trust to make decisions in the best interest of the project. + +If you are interested in becoming a maintainer and satisfy the requirements above, please open up a pull request. The existing maintainers +are given five business days to discuss the candidate, raise objections and cast their vote. Votes take place via pull request comment. +Candidates must be approved by at least 66% of the current maintainers by adding their vote. Only maintainers of the repository that the +candidate is proposed for are allowed to vote. + +If a candidate is approved, a maintainer will contact the candidate to invite the candidate to open a pull request that adds the contributor +to the `MAINTAINERS` file. The candidate becomes a maintainer once the pull request is merged. + +## Maintainer responsibilities + +- Monitor email aliases. +- Monitor Slack (delayed response is perfectly acceptable). +- Triage GitHub issues and perform pull request reviews for other maintainers and the community. +- Triage build issues - file issues for known flaky builds or bugs, and either fix or find someone to fix any main build breakages. +- During GitHub issue triage, apply all applicable labels to each new issue. Labels are extremely useful for future issue follow up. Which labels to apply is somewhat subjective so just use your best judgment. A few of the most important labels that are not self explanatory are: + - **beginner**: Mark any issue that can reasonably be accomplished by a new contributor with this label. + - **help wanted**: Unless it is immediately obvious that someone is going to work on an issue (and if so assign it), mark it help wanted. + - **question**: If it's unclear if an issue is immediately actionable, mark it with the question label. Questions are easy to search for and close out at a later time. Questions can be promoted to other issue types once it's clear they are actionable (at which point the question label should be removed). +- Make sure that ongoing PRs are moving forward at the right pace or closing them. + +## Subprojects + +Athenz subprojects are divided into two flavors: **core** and **non-core**. Definition of a **core** subproject is any repository within the +AthenZ GitHub organization, which is **core** to the delivery of the Athenz project's releases. + +Non-core projects have a strong affiliation with Athenz, but operate similarly to the traditional `contrib/` directory in many open source +projects. For example the auth0 authority or Server metrics interface implementation for Prometheus. + +In most cases the maintainer list will be unique, and the project can have unique release, support, and maintainer processes. +Non-core projects may be written in other languages and therefore require different skills, developer tools, and CI systems than the +core projects. For these reasons, non-core subprojects have a few unique properties that are described in the section +"_Adding non-core subprojects_" below. + +Both core and non-core subprojects must adhere to the CNCF [charter](https://www.cncf.io/about/charter/) and mission. + +Core maintainers have maintainer privileges across all core and non-core projects to help contribute to project health, maintenance, +and release processes within the GitHub organization. For ease of list management, the `MAINTAINERS` file of a sub-project will only +list the sub-project maintainers—the core maintainers of Athenz will not be appended to each subproject. + +## Adding core subprojects + +New core subprojects can request to be added to the AthenZ GitHub organization by submitting a project proposal via public forum +(a `AthenZ/athenz` GitHub issue is the easiest way to provide this proposal). The existing maintainers are given five business days to +discuss the new project, raise objections and cast their vote. Projects must be approved by at least 66% of the current maintainers. + +If a project is approved, a maintainer will add the project to the AthenZ GitHub organization, and make an announcement on a public forum. + +## Adding non-core subprojects + +Non-core subprojects will also submit a project proposal via GitHub issue, and should state that the project is expected to be non-core. + +The proposal should include a proposed list of maintainers who will manage the non-core project and provide general information on support, +releases, stability, and any additional detail useful for the Athenz maintainers to understand the scope and nature of the project. + +The existing maintainers are given five business days to discuss the new project, raise objections and cast their vote. Projects must be +approved by at least 66% of the current maintainers. + +If a project is approved, a core maintainer will add the project to the AthenZ GitHub organization and provide write access for that +repository to the proposed maintainer list, and make an announcement on a public forum. + +Unlike core maintainers, non-core project maintainers are responsible for maintenance tasks in their subproject only. + +## Stepping down policy + +If you're a maintainer but feel you must remove yourself from the list, inform other maintainers that you intend to step down, +and if possible, help find someone to pick up your work. At the very least, ensure your work can be continued where you left off. + +After you've informed other maintainers, create a pull request to remove yourself from the `MAINTAINERS` file. + +The Athenz organization will never forcefully remove a current maintainer, unless a maintainer fails to meet the principles of Athenz community, +or adhere to the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). + +## How are decisions made? + +Decisions are built on consensus between maintainers. Proposals and ideas can either be submitted for agreement via a GitHub issue, PR or +GitHub discussions. + +All proposals, ideas, and decisions by maintainers should either be part of a GitHub issue, PR or GitHub discussions. + +## I'm a maintainer. Should I make pull requests too? + +Yes. Nobody should ever push to master directly. All changes should be made through a pull request. The only exception is when we cut a release +using maven release action, which commits the changes to the version numbers directly to the master branch. + +## Conflict Resolution + +If you have a technical dispute that you feel has reached an impasse with a subset of the community, any contributor may open an issue, +specifically calling for a resolution vote of the current core maintainers to resolve the dispute. The same voting quorums required (2/3) +for adding maintainers will apply to conflict resolution. + +## Credits + +Sections of this document have been borrowed from [Containerd](https://github.com/containerd/project/blob/master/GOVERNANCE.md) and +[CoreDNS](https://github.com/coredns/coredns/blob/master/GOVERNANCE.md) projects. \ No newline at end of file diff --git a/README.md b/README.md index 577bc463a0e..3ec785da037 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ credentials for configured AWS IAM roles. ## Contribute -Please refer to the [contributing file](docs/contributing.md) for information about how to get involved. We welcome issues, questions, and pull requests. +Please refer to the [contributing file](CONTRIBUTING.md) for information about how to get involved. We welcome issues, questions, and pull requests. You can also contact us for any user and development discussions through our groups: diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md deleted file mode 100644 index 56f0ca76353..00000000000 --- a/docs/code_of_conduct.md +++ /dev/null @@ -1,52 +0,0 @@ -# Verizon Media Open Source Code of Conduct - -## Summary -This Code of Conduct is our way to encourage good behavior and discourage bad behavior in our open source projects. We invite participation from many people to bring different perspectives to our projects. We will do our part to foster a welcoming and professional environment free of harassment. We expect participants to communicate professionally and thoughtfully during their involvement with this project. - -Participants may lose their good standing by engaging in misconduct. For example: insulting, threatening, or conveying unwelcome sexual content. We ask participants who observe conduct issues to report the incident directly to the project's Response Team at opensource-conduct@verizonmedia.com. Verizon Media will assign a respondent to address the issue. We may remove harassers from this project. - -This code does not replace the terms of service or acceptable use policies of the websites used to support this project. We acknowledge that participants may be subject to additional conduct terms based on their employment which may govern their online expressions. - -## Details -This Code of Conduct makes our expectations of participants in this community explicit. -* We forbid harassment and abusive speech within this community. -* We request participants to report misconduct to the project’s Response Team. -* We urge participants to refrain from using discussion forums to play out a fight. - -### Expected Behaviors -We expect participants in this community to conduct themselves professionally. Since our primary mode of communication is text on an online forum (e.g. issues, pull requests, comments, emails, or chats) devoid of vocal tone, gestures, or other context that is often vital to understanding, it is important that participants are attentive to their interaction style. - -* **Assume positive intent.** We ask community members to assume positive intent on the part of other people’s communications. We may disagree on details, but we expect all suggestions to be supportive of the community goals. -* **Respect participants.** We expect occasional disagreements. Open Source projects are learning experiences. Ask, explore, challenge, and then _respectfully_ state if you agree or disagree. If your idea is rejected, be more persuasive not bitter. -* **Welcoming to new members.** New members bring new perspectives. Some ask questions that have been addressed before. _Kindly_ point to existing discussions. Everyone is new to every project once. -* **Be kind to beginners.** Beginners use open source projects to get experience. They might not be talented coders yet, and projects should not accept poor quality code. But we were all beginners once, and we need to engage kindly. -* **Consider your impact on others.** Your work will be used by others, and you depend on the work of others. We expect community members to be considerate and establish a balance their self-interest with communal interest. -* **Use words carefully.** We may not understand intent when you say something ironic. Often, people will misinterpret sarcasm in online communications. We ask community members to communicate plainly. -* **Leave with class.** When you wish to resign from participating in this project for any reason, you are free to fork the code and create a competitive project. Open Source explicitly allows this. Your exit should not be dramatic or bitter. - -### Unacceptable Behaviors -Participants remain in good standing when they do not engage in misconduct or harassment (some examples follow). We do not list all forms of harassment, nor imply some forms of harassment are not worthy of action. Any participant who *feels* harassed or *observes* harassment, should report the incident to the Response Team. -* **Don't be a bigot.** Calling out project members by their identity or background in a negative or insulting manner. This includes, but is not limited to, slurs or insinuations related to protected or suspect classes e.g. race, color, citizenship, national origin, political belief, religion, sexual orientation, gender identity and expression, age, size, culture, ethnicity, genetic features, language, profession, national minority status, mental or physical ability. -* **Don't insult.** Insulting remarks about a person’s lifestyle practices. -* **Don't dox.** Revealing private information about other participants without explicit permission. -* **Don't intimidate.** Threats of violence or intimidation of any project member. -* **Don't creep.** Unwanted sexual attention or content unsuited for the subject of this project. -* **Don't inflame.** We ask that victim of harassment not address their grievances in the public forum, as this often intensifies the problem. Report it, and let us address it off-line. -* **Don't disrupt.** Sustained disruptions in a discussion. - -### Reporting Issues -If you experience or witness misconduct, or have any other concerns about the conduct of members of this project, please report it by contacting our Response Team at opensource-conduct@verizonmedia.com who will handle your report with discretion. Your report should include: -* Your preferred contact information. We cannot process anonymous reports. -* Names (real or usernames) of those involved in the incident. -* Your account of what occurred, and if the incident is ongoing. Please provide links to or transcripts of the publicly available records (e.g. a mailing list archive or a public IRC logger), so that we can review it. -* Any additional information that may be helpful to achieve resolution. - -After filing a report, a representative will contact you directly to review the incident and ask additional questions. If a member of the Verizon Media Response Team is named in an incident report, that member will be recused from handling your incident. If the complaint originates from a member of the Response Team, it will be addressed by a different member of the Response Team. We will consider reports to be confidential for the purpose of protecting victims of abuse. - -### Scope -Verizon Media will assign a Response Team member with admin rights on the project and legal rights on the project copyright. The Response Team is empowered to restrict some privileges to the project as needed. Since this project is governed by an open source license, any participant may fork the code under the terms of the project license. The Response Team’s goal is to preserve the project if possible, and will restrict or remove participation from those who disrupt the project. - -This code does not replace the terms of service or acceptable use policies that are provided by the websites used to support this community. Nor does this code apply to communications or actions that take place outside of the context of this community. Many participants in this project are also subject to codes of conduct based on their employment. This code is a social-contract that informs participants of our social expectations. It is not a terms of service or legal contract. - -## License and Acknowledgment. -This text is shared under the [CC-BY-4.0 license](https://creativecommons.org/licenses/by/4.0/). This code is based on a study conducted by the [TODO Group](https://todogroup.org/) of many codes used in the open source community. If you have feedback about this code, contact our Response Team at the address listed above. \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 906df302941..00000000000 --- a/docs/contributing.md +++ /dev/null @@ -1,26 +0,0 @@ -# How to contribute -First, thanks for taking the time to contribute to our project! There are many ways you can help out. - -### Questions - -If you have a question that needs an answer, [create an issue](https://help.github.com/articles/creating-an-issue/), and label it as a question. - -### Issues for bugs or feature requests - -If you encounter any bugs in the code, or want to request a new feature or enhancement, please [create an issue](https://help.github.com/articles/creating-an-issue/) to report it. Kindly add a label to indicate what type of issue it is. - -### Contribute Code -We welcome your pull requests for bug fixes. To implement something new, please create an issue first so we can discuss it together. - -***Creating a Pull Request*** -Please follow [best practices](https://github.com/trein/dev-best-practices/wiki/Git-Commit-Best-Practices) for creating git commits. - -When your code is ready to be submitted, [submit a pull request](https://help.github.com/articles/creating-a-pull-request/) to begin the code review process. - -We only seek to accept code that you are authorized to contribute to the project. We have added a pull request template on our projects so that your contributions are made with the following confirmation: - -> I confirm that this contribution is made under the terms of the license found in the root directory of this repository's source tree and that I have the authority necessary to make this contribution on behalf of its copyright owner. - -## Code of Conduct - -We encourage inclusive and professional interactions on our project. We welcome everyone to open an issue, improve the documentation, report bug or submit a pull request. By participating in this project, you agree to abide by the [Verizon Media Code of Conduct](code_of_conduct.md). If you feel there is a conduct issue related to this project, please raise it per the Code of Conduct process and we will address it.