From 133c0f14c061381b3dda7f27f5bde2b59ea8dc77 Mon Sep 17 00:00:00 2001 From: = <=> Date: Wed, 8 Nov 2023 01:11:19 +0530 Subject: [PATCH] feat(gcbs): adds CONTRIBUTING.md --- docs/CONTRIBUTING.md | 506 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 506 insertions(+) create mode 100644 docs/CONTRIBUTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..812da84 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,506 @@ +# Contributing to gCBS + +First off, thanks for taking the time to contribute! +We are so happy to have you! :tada: + +There are opportunities to contribute to gCBS at any level. +It doesn't matter if you are just getting started with Web/App Technologies or are the most +weathered expert, we can use your help. + +**No contribution is too small and all contributions are valued.** + +This guide will help you get started. +**Do not let this guide intimidate you.** +It should be considered a map to help you navigate the process. + +You can also get help with contributing on our [Discord server][discord] +Please join us! + +[discord]: https://discord.gg/5Tj7DEED + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Contributing in Issues](#contributing-in-issues) + - [Asking for General Help](#asking-for-general-help) + - [Submitting a Bug Report](#submitting-a-bug-report) + - [Triaging a Bug Report](#triaging-a-bug-report) + - [Resolving a Bug Report](#resolving-a-bug-report) +- [Pull Requests](#pull-requests) + - [Cargo Commands](#cargo-commands) + - [Commits](#commits) + - [Opening the Pull Request](#opening-the-pull-request) + - [Discuss and update](#discuss-and-update) + - [Commit Squashing](#commit-squashing) +- [Reviewing Pull Requests](#reviewing-pull-requests) + - [Review a bit at a time](#review-a-bit-at-a-time) + - [Be aware of the person behind the code](#be-aware-of-the-person-behind-the-code) + - [Abandoned or Stalled Pull Requests](#abandoned-or-stalled-pull-requests) +- [Keeping track of issues and PRs](#keeping-track-of-issues-and-prs) + - [Area](#area) + - [Category](#category) + - [Calls for participation](#calls-for-participation) + - [Metadata](#metadata) + - [Priority](#priority) + - [RFCs](#rfcs) + - [Status](#status) + +## Code of Conduct + +The GCBS project adheres to the [Contributor-Convenant][cc]. +This describes the _minimum_ behavior expected from all contributors. + +For a Basic Outline,Check out [p-society's repo] related to the development 💻 practices to be followed by the org. + +[p-society's repo]: https://github.com/p-society/meta +[cc]: https://www.contributor-covenant.org/ + +## Contributing in Issues + +For any issue, there are fundamentally three ways an individual can contribute: + +1. By opening the issue for discussion: For instance, if you believe that you + have discovered a bug in GCBS, creating a new issue in [the + p-society/gCBS issue tracker][issue] is the way to report it. + +2. By helping to triage the issue: This can be done by providing supporting + details (a test case that demonstrates a bug), providing suggestions on how + to address the issue, or ensuring that the issue is tagged correctly. + +3. By helping to resolve the issue: Typically this is done either in the form of + demonstrating that the issue reported is not a problem after all, or more + often, by opening a Pull Request that changes some bit of something in + GCBS in a concrete and reviewable manner. + +[issue]: https://github.com/p-society/p-society/gCBS + +**Anybody can participate in any stage of contribution**. +We urge you to participate in the discussion around bugs and participate in +reviewing PRs. + +### Asking for General Help + +If you have reviewed existing documentation and still have questions or are +having problems, you can asking for help at [p-society's discord server]. + +In exchange for receiving help, we ask that you contribute back a documentation +PR that helps others avoid the problems that you encountered. + +[p-society's discord server]: https://discord.gg/5Tj7DEED + +### Submitting a Bug Report + +When opening a new issue in the gCBS issue tracker, you will be presented +with a basic template that should be filled in. +If you believe that you have uncovered a bug, please fill out this form, +following the template to the best of your ability. +Do not worry if you cannot answer every detail, just fill in what you can. + +The two most important pieces of information we need in order to properly +evaluate the report is a description of the behavior you are seeing and a simple +test case we can use to recreate the problem on our own. +If we cannot recreate the issue, it becomes impossible for us to fix. + +See [How to create a Minimal, Complete, and Verifiable example][mcve]. + +[mcve]: https://stackoverflow.com/help/mcve + +### Triaging a Bug Report + +Once an issue has been opened, it is not uncommon for there to be discussion +around it. +Some contributors may have differing opinions about the issue, including whether +the behavior being seen is a bug or a feature. +This discussion is part of the process and should be kept focused, helpful, and +professional. + +Short, clipped responses — that provide neither additional context nor +supporting detail — are not helpful or professional. +To many, such responses are simply annoying and unfriendly. + +Contributors are encouraged to help one another make forward progress as much as +possible, empowering one another to solve issues collaboratively. +If you choose to comment on an issue that you feel either is not a problem that +needs to be fixed, or if you encounter information in an issue that you feel is +incorrect, explain why you feel that way with additional supporting context, and +be willing to be convinced that you may be wrong. +By doing so, we can often reach the correct outcome much faster. + +### Resolving a Bug Report + +In the majority of cases, issues are resolved by opening a Pull Request. +The process for opening and reviewing a Pull Request is similar to that of +opening and triaging issues, but carries with it a necessary review and approval +workflow that ensures that the proposed changes meet the minimal quality and +functional guidelines of the gCBS project. + +## Pull Requests + +Pull Requests are the way concrete changes are made to the code, documentation, +and dependencies in the gCBS repository. + +Even tiny pull requests (e.g., one character pull request fixing a typo in API +documentation) are greatly appreciated. +Before making a large change, it is usually a good idea to first open an issue +describing the change to solicit feedback and guidance. +This will increase the likelihood of the PR getting merged. + +### Commits + +It is a recommended best practice to keep your changes as logically grouped as +possible within individual commits. +There is no limit to the number of commits any single Pull Request may have, and +many contributors find it easier to review changes that are split across +multiple commits. + +Please adhere to the general guideline that you should never force push to a +publicly shared branch. +Once you have opened your pull request, you should consider your branch publicly shared. +Instead of force pushing you can just add incremental commits; +this is generally easier on your reviewers. +If you need to pick up changes from main, you can merge main into your branch. + +A reviewer might ask you to rebase a long-running pull request +in which case force pushing is okay for that request. + +Note that squashing at the end of the review process should also not be done, +that can be done when the pull request is integrated via GitHub. + + +#### Commit message guidelines + +Each commit message consists of a header, an optional body, and an optional +footer. + +```text +
+ + + + +``` + +The `header` is mandatory and must conform to the +[commit message header](#commit-message-header) format. + +The `body` is optional. +When the body is present it must be at least 20 characters long and must conform +to the [commit message body](#commit-message-body) format. + +The `footer` is optional. +The [commit message footer](#commit-message-footer) format describes what the +footer is used for and the structure it must have. + +##### Commit message header + +```text +(): +│ │ │ +│ │ └── Summary in present tense. +| | Not capitalized. +| | No period at the end. +│ │ +│ └── Commit Scope(Which Part?) +| +| +│ +└── Commit Type: build | chore | ci | docs | feat | fix | perf | refactor | test +``` + +The `` and `` fields are mandatory, the (``) field is +optional. + +`` must be one of the following: + +- `build`: Changes that affect the build system or external dependencies. +- `chore`: Changes such as fixing formatting or addressing warnings or lints, or + other maintenance changes +- `ci`: Changes to our CI configuration files and scripts (examples: `workflows`, + `dependabot`, `renovate`) +- `docs`: Documentation only changes +- `feat`: A new feature +- `fix`: A bug fix +- `perf`: A code change that improves performance +- `refactor`: A code change that neither fixes a bug nor adds a feature +- `test`: Adding missing tests or correcting existing tests + +`` should be the name of the API affected (as perceived by the person +reading the changelog generated from commit messages). + +The following is the list of supported scopes: + +- TBD + + +Use the `` field to provide a succinct description of the change: + +- Use the imperative, present tense: "change" not "changed" nor "changes". +- Don't capitalize the first letter. +- No period (.) at the end. + +##### Commit message body + +Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor +"fixes". + +Explain the motivation for the change in the commit message body. +This commit message should explain why you are making the change. +You can include a comparison of the previous behavior with the new behavior in +order to illustrate the impact of the change. + +##### Commit message footer + +The footer can contain information about breaking changes and deprecations and +is also the place to reference GitHub issues, Jira tickets, and other PRs that +this commit closes or is related to. +For example: + +```text +BREAKING CHANGE: + + + + +Fixes # +``` + +or + +```text +DEPRECATED: + + + + +Closes # +``` + +Breaking Change section should start with the phrase "BREAKING CHANGE: " +followed by a summary of the breaking change, a blank line, and a detailed +description of the breaking change that also includes migration instructions. + +Similarly, a Deprecation section should start with "DEPRECATED: " followed by a +short description of what is deprecated, a blank line, and a detailed +description of the deprecation that also mentions the recommended update path. + +If the commit reverts a previous commit, it should begin with `revert:`, +followed by the header of the reverted commit. +The content of the commit message body should contain: + +- Information about the SHA of the commit being reverted in the following + format: `This reverts commit `. +- A clear description of the reason for reverting the commit message. + +Sample commit messages: + +1. ```text + feat(basketball-api): add support for winrate. + + Implement Redirection flow support. This can be used by any flow that + requires redirection. + + Fixes #123 + ``` + +2. ```text + chore: run formatter + ``` + +3. ```text + fix(config): fix binary name displayed in help message + ``` + +### Opening the Pull Request + +From within GitHub, opening a new Pull Request will present you with a +[template] that should be filled out. Please try to do your best at filling out +the details, but feel free to skip parts if you're not sure what to put. + +[template]: /.github/PULL_REQUEST_TEMPLATE.md + +### Discuss and update + +You will probably get feedback or requests for changes to your Pull Request. +This is a big part of the submission process so don't be discouraged! +Some contributors may sign off on the Pull Request right away, others may have +more detailed comments or feedback. +This is a necessary part of the process in order to evaluate whether the changes +are correct and necessary. + +**Any community member can review a PR and you might get conflicting feedback**. +Keep an eye out for comments from code owners to provide guidance on conflicting +feedback. + +**Once the PR is open, do not rebase the commits**. +See [Commit Squashing](#commit-squashing) for more details. + +### Commit Squashing + +In most cases, **do not squash commits that you add to your Pull Request during +the review process**. +When the commits in your Pull Request land, they may be squashed into one commit +per logical change. +Metadata will be added to the commit message (including links to the Pull +Request, links to relevant issues, and the names of the reviewers). +The commit history of your Pull Request, however, will stay intact on the Pull +Request page. + +## Reviewing Pull Requests + +**Any gCBS community member is welcome to review any pull request**. + +All gCBS contributors who choose to review and provide feedback on Pull +Requests have a responsibility to both the project and the individual making the +contribution. +Reviews and feedback must be helpful, insightful, and geared towards improving +the contribution as opposed to simply blocking it. +If there are reasons why you feel the PR should not land, explain what those are. +Do not expect to be able to block a Pull Request from advancing simply because +you say "No" without giving an explanation. +Be open to having your mind changed. +Be open to working with the contributor to make the Pull Request better. + +Reviews that are dismissive or disrespectful of the contributor or any other +reviewers are strictly counter to the Code of Conduct. + +When reviewing a Pull Request, the primary goals are for the codebase to improve +and for the person submitting the request to succeed. +**Even if a Pull Request does not land, the submitters should come away from the +experience feeling like their effort was not wasted or unappreciated**. +Every Pull Request from a new contributor is an opportunity to grow the +community. + +### Review a bit at a time + +Do not overwhelm new contributors. + +It is tempting to micro-optimize and make everything about relative performance, +perfect grammar, or exact style matches. +Do not succumb to that temptation. + +Focus first on the most significant aspects of the change: + +1. Does this change make sense for gCBS? +2. Does this change make gCBS better, even if only incrementally? +3. Are there clear bugs or larger scale issues that need attending to? +4. Is the commit message readable and correct? + If it contains a breaking change is it clear enough? + +Note that only **incremental** improvement is needed to land a PR. +This means that the PR does not need to be perfect, only better than the status +quo. +Follow up PRs may be opened to continue iterating. + +When changes are necessary, _request_ them, do not _demand_ them, and **do not +assume that the submitter already knows how to add a test or run a benchmark**. + +Specific performance optimization techniques, coding styles and conventions +change over time. +The first impression you give to a new contributor never does. + +Nits (requests for small changes that are not essential) are fine, but try to +avoid stalling the Pull Request. +Most nits can typically be fixed by the gCBS collaborator landing the +Pull Request but they can also be an opportunity for the contributor to learn a +bit more about the project. + +It is always good to clearly indicate nits when you comment: e.g. +`Nit: change foo() to bar(). But this is not blocking.` + +If your comments were addressed but were not folded automatically after new +commits or if they proved to be mistaken, please, [hide them][hiding-a-comment] +with the appropriate reason to keep the conversation flow concise and relevant. + +### Be aware of the person behind the code + +Be aware that _how_ you communicate requests and reviews in your feedback can +have a significant impact on the success of the Pull Request. +Yes, we may land a particular change that makes gCBS better, but the +individual might just not want to have anything to do with gCBS ever +again. +The goal is not just having good code. + +### Abandoned or Stalled Pull Requests + +If a Pull Request appears to be abandoned or stalled, it is polite to first +check with the contributor to see if they intend to continue the work before +checking if they would mind if you took it over (especially if it just has nits +left). +When doing so, it is courteous to give the original contributor credit for the +work they started (either by preserving their name and email address in the +commit log, or by using an `Author:` meta-data tag in the commit. + +## Keeping track of issues and PRs + +The gCBS GitHub repository has a lot of issues and PRs to keep track of. +The section is primarily targeted at maintainers. +Most contributors aren't able to set these labels. + +### Area + +The area label describes the area relevant to this issue or PR. + +- TBD + + +### Category + +- **C-bug**: This issue is a bug report or this PR is a bug fix. +- **C-doc**: This issue/PR concerns changes to the documentation. +- **C-feature**: This issue is a feature request or this PR adds new features. +- **C-refactor**: This issue/PR concerns a refactor of existing behavior. +- **C-tracking-issue**: This is a tracking issue for a proposal or for a + category of bugs. + +### Calls for participation + +- **E-easy**: This is easy, ranging from quick documentation fixes to stuff you + can do after getting a basic idea about our product. +- **E-medium**: This is not `E-easy` or `E-hard`. +- **E-hard**: This either involves very tricky code, is something we don't know + how to solve, or is difficult for some other reason. + +### Priority + +- **P-low**: This is a low priority issue. +- **P-medium**: This is not `P-low` or `P-high`. +- **P-high**: This is a high priority issue and must be addressed quickly. + +### RFCs + +- **RFC-in-progress**: This RFC involves active discussion regarding substantial + design changes. +- **RFC-resolved**: This RFC has been resolved. + +### Status + +The status label provides information about the status of the issue or PR. + +- **S-awaiting-triage**: This issue or PR is relatively new and has not been + addressed yet. +- **S-blocked**: This issue or PR is blocked on something else, or other + implementation work. +- **S-design**: This issue or PR involves a problem without an obvious solution; + or the proposed solution raises other questions. +- **S-in-progress**: The implementation relevant to this issue/PR is underway. +- **S-invalid**: This is an invalid issue. +- **S-needs-conflict-resolution**: This PR requires merge conflicts to be + resolved by the author. +- **S-needs-reproduction-steps**: This behavior hasn't been reproduced by the + team. +- **S-unactionable**: There is not enough information to act on this problem. +- **S-unassigned**: This issue has no one assigned to address it. +- **S-waiting-on-author**: This PR is incomplete or the author needs to address + review comments. +- **S-waiting-on-reporter**: Awaiting response from the issue author. +- **S-waiting-on-review**: This PR has been implemented and needs to be reviewed. +- **S-wont-fix**: The proposal in this issue was rejected and will not be + implemented. + +Any label not listed here is not in active use. + +_Adapted from the [Juspay/Hyperswitch Contributing.md][Juspay/Hyperswitch Contributing.md]._ + +[Juspay/Hyperswitch Contributing.md]: https://github.com/juspay/hyperswitch/blob/main/docs/CONTRIBUTING.md