From e0c6c0ea9a02d37ba9251198661dd0865db41813 Mon Sep 17 00:00:00 2001 From: Kylee Fields <43586156+kyleecodes@users.noreply.github.com> Date: Tue, 12 Dec 2023 16:59:32 -0500 Subject: [PATCH] Update CONTRIBUTING.md Simplified directions for following open-source best practices. New table of contents. Improved, project-agnostic guidance on git flows. --- CONTRIBUTING.md | 252 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 171 insertions(+), 81 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b4d3cd..27b782a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,14 +10,52 @@ While Chayn is hybrid between paid staff and volunteers now, we cherish our volu Next, let's get started... πŸŽ‰ +# Table of Contents +- [New Contributor Guide:](#new-contributor-guide) + - [Prerequisites](#prerequisites) + - [Where Can I Get Help?](#where-can-i-get-help) + - [What kind of contributions does Chayn want?](#what-kind-of-contributions-does-chayn-want) +- [The Contribution Process Guide:](#the-contribution-process-guide) + 1. [Read the README and Code of Conduct](#1-read-the-readme-and-code-of-conduct) + 2. [Claim an Issue](#2-claim-an-issue) + 3. [Fork the Repo and Create a New Branch](#3-fork-the-repo-and-create-a-new-branch) + 4. [Commit Changes Using Open-Source Standards](#4-commit-changes-using-open-source-standards) + 5. [Sync Fork if Needed](#5-sync-your-fork-if-needed) + 6. [Push Changes to GitHub](#6-push-changes-to-github) + 7. [Make a Pull Request to Chayn](#7--make-a-pull-request-to-chayn) + # New Contributor Guide -If you are new to GitHub and git version control, here are some resources to help you get started: + **If you are experienced in making open-source contributions, please feel free to skip ahead to the [Contribution Process Guide](#the-contribution-process-guide).** + +## Prerequisites + + + If you are new to GitHub and git version control, here are some resources to help you get started: + +- [Getting Started with First Time Git Setup](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) +- [Learn the GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow) +- [Git Basic Branching & Merging Guide](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging) +- [How to Collaborate with Pull Requests](https://docs.github.com/en/github/collaborating-with-pull-requests) +- [Git Cheatsheet](https://education.github.com/git-cheat-sheet-education.pdf) *(we highly recommend saving this for future reference!)* + +Here are prerequisites you should meet before contributing to Chayn's GitHub: +- git version control configuration +- a GitHub account +- fundamental knowledge of the GitHub and git version control flow (fork, clone, push, commit, branches, etc.) + +**It is not required that you have experience contributing to open-source projects on GitHub!** Chayn aims to be a safe space for contributors of all skill-levels to build their skills while making an impact in digital public goods. If this is your first contribution, we recommend saving the cheatsheet linked above for future reference, learning how to navigate the GitHub and git version control docs, and in general -- *learn as you go.* The Chayn team is here to help. You got this! πŸ’ͺ + +## Where can I get help? +Chayn maintainers and developers are here to help! We aim to give a safe space for contributors of all skill levels to build their skills while making an impact. 🀝 -- [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) -- [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) -- [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) -- [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) +You can ask Chayn team members questions at any point during your contribution in the following places on GitHub: + +- Issue discussions in an issue you're assigned to or interested in. +- Pull request discussions for your contribution. +- Or, create a new issue with the `type: question / suggestion` label. + +Chayn team members will respond within 3 business days. ## What kind of contributions does Chayn want? @@ -27,10 +65,10 @@ Chayn is open to all kinds of contributions, such as: - additional software tests - code of any kind (enhancements, new features, maintenance) -Just no spamming (such as unwanted, minor documentation and HTML/CSS changes) please! +Just no spamming (such as unwanted, minor documentation and HTML/CSS changes) please! 🚫 -# The Contribution Process: -### Contribution Process Outline: +# The Contribution Process Guide: +### The Contribution Process Outline: 1. [Read the README and Code of Conduct](#1-read-the-readme-and-code-of-conduct) 2. [Claim an Issue](#2-claim-an-issue) 3. [Fork the Repo and Create a New Branch](#3-fork-the-repo-and-create-a-new-branch) @@ -40,127 +78,179 @@ Just no spamming (such as unwanted, minor documentation and HTML/CSS changes) pl 7. [Make a Pull Request to Chayn](#7--make-a-pull-request-to-chayn) ## 1. **Read the README and Code of Conduct:**. -To learn the foundations of the project, please read the project's [README](/README.md). Contributing means you have agreed to our [Code of Conduct](/CODE_OF_CONDUCT.md) +First, read the project's [README](/README.md) for project-specific directions on how to set up your development environment and git flow. -**Note: If you are making no-code changes in the README or any other markdown / text files, it may not be required to follow all of these steps in our Contributing Guide. Instead, you may edit these files and submit a PR directly in GitHub, without setting up environment variables and or requiring tests to pass in your fork.** +Contributing means you have agreed to our [Code of Conduct](/CODE_OF_CONDUCT.md). + +**Note: For no-code contributors,** if you are editing the `README` file or any other markdown / text files, it is NOT required to set up environment variables, run the app locally, and pass tests. You can make your changes entirely in the GitHub UI (in the web browser) after forking the Chayn repository you are working on and creating a new feature branch. ## 2. **Claim an Issue:** -**Please ask to be assigned an issue, this helps us keep track of contributor progress. We may deny your PR if the issue is already assigned to someone who asked.** +**First, please ask to be assigned an issue, this helps us keep track of contributor progress. We may deny your PR if the issue is already assigned to someone who asked.** - **If creating an issue:** - Check that your issue doesn't already exist and follow our issue templates for creating new issues. + Check that your issue doesn't already exist and follow our issue templates for creating new issues. For a detailed guide on creating issues, read this guide on GitHub: [Creating an Issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-an-issue). - **If contributing to an existing issue:** Please comment on it asking for the issue to be assigned to you. -**Check Issue Labels:** +### How to Use Issue Labels: + +Note: all unassigned issues are available to contributors, regardless of their label. + - Scan our issue `labels` to find issues that suit you: - - The `good first issue` label is for problems or updates we think are ideal for beginners. - - The `moderate` label is for problems or updates that may take 1-2 days and will require some knowledge of the codebase. - - The `advanced` is for problems or updates that may take more time, say around 2-4 days. These will require more in-depth knowledge of the codebase. - - We suggest starting with a `good first issue` to get comfortable with the codebase before moving on. + - The `good first issue` and `first-timers-friendly` labels are best for new contributors. + - The `help wanted` label indicates that Chayn is inviting contributors to help. While contributors can contribute to any unassigned issue, issues with this label are specifically looking for help outside of Chayn's dev team. + - The `complexity: obvious` label is for issues that take less than 1 day to complete, and require little to no prior experience with the codebase. + - The `complexity: moderate` label is for issues that may take 1-2 days to complete, and will require some knowledge of the codebase. + - The `complexity: advanced` is for issues that may take more time, possibly 3+ days. These will require more in-depth knowledge of the codebase. + - We suggest starting with issues labeled `good first issue` or `complexity: obvious` to get comfortable with the codebase before moving onto more complex issues. -**How We Manage Issues:** +### How We Manage Issues: - Issues can be assigned to multiple people if everyone agrees to collaborate! - Consider if an issue would be best broken up into multiple, smaller issues. If so, feel free to create those issues! - If an assigned issue is abandoned, we will unassign the issue after tagging you if we receive no response. - If you can no longer complete an issue you're assigned to, we understand life happens! Please comment on the issue and we will unassign you. - For complex issues, please report your progress in the issue discussions by tagging the issue author or Chayn maintainer who assigned you, and ticking off the checkboxes in the issue description. -**If you need more clarifying information about the issue, please tag us (issue author or Chayn maintainer who assigned the issue to you) to ask questions in the issues discussions at any point during your contribution. We are happy to help! You will hear back from us within 3 days, and we are online daily during Hacktober.** +🀝 **If you need more clarifying information about the issue, please tag us (issue author or Chayn maintainer who assigned the issue to you) to ask questions in the issues discussions at any point during your contribution. We are happy to help! You should hear back from us within 3 days.** ## 3. **Fork the Repo and Create a New Branch:** - - Fork the Chayn repo you want to make changes on, then create a new feature branch on your fork. This new branch will be where you make changes. - - Name your new branch with a label (check the issue labels) and description, such as `dependencies/update-node` - - Alternatively, you may name the branch with your GitHub name and descriptive title, such as `chayntech/update-node` -## 4. **Commit Changes Using Open-Source Standards:** -Follow the following open-source standards for structuring and formatting your commits and commit messages: +First, read the **Git Flow and Deployment** section in your project's `README` file to learn of any project-specific requirements. Generally, the git flow is the same among all repositories, however, each project may slightly vary. -**Commit Message Structure:** -- **Commit Title**: (< 50 char) first line is the commit title. This should be capitalized and contain a short, one-line summary. -- Blank line to separate title from body. This ensures β€œgit log” can parse logs correctly. -- **Commit Description**: (< 72 char) explains the **why** of a commit rather than **how.** -- See [link](https://cbea.ms/git-commit/) for more detail on structuring commits. +Next, follow the five-step process below to create your own copy of Chayn's code to work on. -**Commit Formatting:** -- To keep commit messages readable, your commit message should wrap text to avoid long, single lines of text. -- Keep commits small and distinct. A PR can have multiple commits, but only if each commit is distinctive and relevant in the PR. -- Check that no secrets and no unwanted, irrelevant files are being commited. Update `.gitignore` as needed. +### Make Your Own Copy of Chayn's Code To Work On: + + 1. **Fork the Chayn repository** you want to make changes on in GitHub: + - In the GitHub web browser, navigate to the Chayn repository you want to contribute to, then select "Fork" in the top-right menu. For more in-depth guidance, read this forking guide in the GitHub Docs: [How to Fork a Repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo). + - Ensure that you are forking from the **default branch**. Depending on the project, the default branch may **not** be `main`. In general, GitHub will automatically fork the default branch, but it's important to verify the default branch for your project in the `README` file. + 2. **Create a new feature branch on your fork.** This feature branch will be where you make changes. + - Navigate to your forked repository (found on your GitHub profile in your list of repositories) then select the drop-down menu of branches in the top-left corner. There will be an option to create a new branch. For more in-depth guidance, read this guide on creating new branches in the GitHub Docs: [Branching Guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository). + - We recommend naming your new feature branch intuitively: + - Branch naming option 1: use label and description, such as `dependencies/update-node`. + - Branch naming option 2: use your GitHub name and descriptive title, such as `chayntech/update-node`. + 3. **Clone the fork to your computer** where you will run the application locally. Cloning will be an option in the top right drop-down menu titled "Code" on your forked repo. If making no-code changes to markdown / text files, you can bypass this step and edit directly in GitHub inside your new feature branch. For more guidance on cloning, visit this GitHub guide: [How to Clone a Repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). -## 5. **Sync Your Fork if Needed:** -If the Chayn repo you forked from (the upstream repo) is updated, you will need to pull these changes from upstream before you push. One way to tell if the upstream repo has been updated is if there is a message displayed when viewing your forked repo in GitHub that says something like "This branch is 1 commit behind chayn:bloom-frontend". + 4. **Switch to your feature branch locally** before making code changes by running the following command: + ``` + git checkout + ``` + + To create new branches locally, run this git command to create a new branch and switch to it: -To update your fork, first sync your forked default branch (main, master, or develop branch depending on the project) and then merge those changes into your feature branch. Always make sure that your default branch is up-to-date first before your feature branch. *Note: there are many methods of syncing forks and updating branches, this documentation will focus on the git merging method because rebasing comes with more risks to unintentionally overwriting git history. Please see the additional resources listed at the end of this section for more info.* + ``` + git checkout -b + ``` -To sync with upstream changes, first sync your default branch by running the commands below or [following this guide on syncing in the GitHub UI](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork#syncing-a-fork-branch-from-the-web-ui). -``` -# Add a new remote upstream repository -git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git + 5. **Verify that you working in the correct feature branch** by running this command (you should see your feature branch as the selected branch): + ``` + git branch + ``` + For more guidance on managing branches with git version control, visit this guide: [Git Basic Branching](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging). -# Verify remote upstream -git remote -v +### What if I Clone from Chayn's Repo and Not My Fork? -# Sync your fork -git fetch upstream +Cloning from a forked repository is necessary because contributors do not have permission to push directly to Chayn's repositories. To verify that your cloned repo is from your fork, use the `git remote -v` command and check that your forked repo is set as the `origin`. -# Switch to default branch -git checkout main +For more guidance on updating your remote origin, please visit this guide on GitHub: [Getting Started with Managing Remote Repositories](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories). -# Merge upstream with main branch -git merge upstream/main -``` -Next, merge the updated default branch into your feature branch. -If you used the GitHub UI to sync the default branch of your remote fork, you will need to `git pull` those changes into your local default branch. Then, merge those changes into your feature branch: +## 4. **Commit Changes Using Open-Source Standards:** + +Whether you are a beginner developer or experienced, we recommend all contributors use open-source best practices by following the six standards listed below. + +### How to Properly Commit Changes: +1. **Keep commits small and distinct.** A PR can have multiple commits, but only if each commit is distinctive and relevant in the PR. +2. **Comment your code** to describe what it's doing, especially if making extensive code changes. +3. **Run linters** to properly format your code before making commits. Directions for running linters are in the repository's `README` file. +4. **Run tests and check that they pass.** Directions for running tests are in the repository's `README` file. + + **Important Note about Tests:** We are currently making upgrades to our products performances. Therefore, some tests may need to be ran multiple times before they pass, and some may not pass at all. We recommend frequently running tests as you make code changes, then at your own discretion, deciding which tests fail due to your code changes, and fixing them so that they pass. Please reach out to Chayn staff in issue discussions if you encounter any issues with tests. Thank you for your patience! + +5. **Check that no secrets (sensitive API keys and environment variables) and no unwanted, irrelevant files are commited.** Everything you commit to Chayn will be public, please be vigilant about not commiting sensitive information. Be sure to update `.gitignore` as needed, making sure to clean the `.gitignore` cache whenever new files are added to it. Learn more about properly using the `.gitignore` file to ignore specific files in this GitHub guide: [Ignoring Files Guide](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files). + +6. **Write readable commit messages** as demonstrated below: + +### How to Write Readable Commit Messages: + +**Basic Anatomy of a Commit Message:** +``` +git commit -m -m <description> ``` -# Checkout default branch -git checkout main -# Pull changes from your remote -git pull +**Commit Title:** +- (< 50 char) first line is the commit title. This should be capitalized and contain a short, one-line summary. +- Blank line to separate title from body. This ensures β€œgit log” can parse logs correctly. + +**Commit Description:** +- (< 72 char) explains the **why** of a commit rather than **how.** +- To keep commit messages readable, your commit message should wrap text to avoid long, single lines of text. +- See [link](https://cbea.ms/git-commit/) for more detail on structuring commits. -# Switch to feature branch -git checkout FEATURE-BRANCH -# Merge changes in main into feature branch -git merge main +**Example: Git Commit Message (Good):** ``` -If you used the command line to sync your local forked repo with the upstream repo, switch to your feature branch and merge the updated default branch into it: +fix: fix foo to enable bar + +Fix bug preventing users from submitting the subscribe form ``` -# Switch to your feature branch -git checkout FEATURE-BRANCH -# Merge default branch into feature branch -git merge main +**Example: Git Commit Message (Bad):** +``` +fixed bug on landing page ``` -Use `git log` to check that commits have been updated. In your feature branch history, you should see the updated commits pulled from upstream, then your new commit, followed by a merge commit. Please resolve any merge conflicts (resources below) and let us know if you have any questions. -**Helpful Resources for Updating Forks:** +**Note: While following these directions perfectly is not expected, Chayn maintainers may ask you to implement these standards during your pull request review.** + +## 5. **Sync Your Fork if Needed:** +If the default branch of the Chayn repository you forked from has been updated (referred to as the "upstream repository"), it is recommended to keep your forked repository up to date with these changes. + +### How Can I Tell if the Upstream Repository has been Updated? + +Navigate to the GitHub UI (in the web browser) and view your forked repository, you will see a notification alerting you that your fork has less commits than the the upstream. See an example in the guide linked below. + +### How Do I Update my Fork? + +**We highly recommend referring to this guide in GitHub's docs on how to sync your fork: [GitHub Docs: Syncing Your Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork).** You can sync your fork using the GitHub UI (web browser), command line, or GitHub's CLI by following the directions in the GitHub Docs. + +In addition to following the guide linked above, always make sure that your default branch is up-to-date first *before* your feature branch. After syncing your default branch with the upstream, then **merge** those updates into your feature branch. + +Next, verify that the git history on your feature branch is correctly synced with the upstream. One way to do this is to use the `git log` command to check commit history. In your feature branch history, you should see the updated commits pulled from upstream, then your new commits, followed by a merge commit. + +Finally, please resolve any merge conflicts by manually editing the conflicting files and deciding how the conflicting changes should be merged. You can refer to the resources linked below for more guidance on how to handle merge conflicts. + +**For more guidance on updating forks, read the following guides:** - [GitHub Docs: About Merge Methods](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github) - [GitHub Docs: Resolving Merge Conflicts on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) - [GitHub Docs: Configuring a Remote Repo for a Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork) - [FreeCodeCamp: How to Sync Your Fork with the Original Git Repo](https://www.freecodecamp.org/news/how-to-sync-your-fork-with-the-original-git-repository/) +**Note: We understand merge conflicts can feel scary for new devs! While we encourage contributors to update their forks prior to pull request, please do not hesitate to submit a pull request despite fork syncing issues or merge conflicts. If you have any questions or concerns, please let Chayn maintainers know in GitHub. Chayn maintainers are here to help!** ## 6. **Push Changes to GitHub:** -Push your changes to your remote, forked repo. -**Before pushing changes, check for the following:** -- Your change have brief, descriptive code comments explaining your code. -- Check that your tests pass. Note: Some tests may need to be ran multiple times before they pass, thank you for your patience as we are upgrading our app's performance. -- Run our linters on updated files to ensure uniform code formatting. -- Ensure that no secret tokens are being pushed to GitHub! Files containing secrets should be listed in `.gitignore` -- When finished making commits, push your changes to your remote fork branch. + +**Before pushing changes to GitHub, please check that you have followed the standards listed in the [Commit Changes Using Open-Source Standards](#4-commit-changes-using-open-source-standards) section of this document.** + +In addition to following the best practices listed here, we ask that you **carefully ensure** that there are **no secrets and unwanted files being pushed.** + +We recommend using the `git status` command to verify that the right files are being pushed. + +**For more guidance on pushing changes to GitHub, read the following guides:** +- [Git Docs: git-status command](https://git-scm.com/docs/git-status) +- [Git Docs: git push command](https://github.com/git-guides/git-push) +- [GitHub Docs: How to Push to Remote Repositoru](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository) + ## 7 . **Make a Pull Request to Chayn:** - - Make sure to link your corresponding issue in your PR's description and follow the PR templates instructions. - - Include detailed and concise explanations of the changes you made. - - Include images in the description, if applicable. - - Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so a maintainer can update the branch for a merge. - - Be available for discussions that may arise and to make [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) that may be required before merging. - - Once the review has passed, it will merge to the *develop* branch. - - To deploy, look at project readme for project specific instructions. +For a more in-depth guide on creating pull requests, please refer to this guide in the GitHub Docs: [Creating a Pull Request Guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). We recommend opening a pull request in the GitHub UI (GitHub in the web browser.) + +**Important Note: Check that you are forking against the correct default branch in the upstream Chayn repository. While GitHub *should* automatically fork against the default branch, if the default branch is not called `main` (some Chayn repositories use the `develop` branch as the default), GitHub is known to accidentally fork against main instead of the correct default branch. However, this is not a common issue.** + +**Next, complete the tasklist in the pull request template.** This is a brief tasklist that is only viewable when creating a pull request. + +Finally, submit your pull request, and be available for discussions that may arise and to make [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) that may be required before merging. -### Get merged and celebrate! πŸŽ‰ +## Get merged and celebrate! πŸŽ‰ Woohoo! Once your PR is merged, your changes will be public on GitHub!