From 4b22c829fe46e26cf4d51b55eafe061be12cdfb2 Mon Sep 17 00:00:00 2001 From: Silas Morgan Date: Tue, 25 Jul 2023 03:34:35 -0400 Subject: [PATCH 1/2] stage Readme.md --- contributor_docs/README.md | 2 +- contributor_docs/contributing_documentation.md | 2 +- contributor_docs/contributor_guidelines.md | 14 +++++++------- contributor_docs/release_process.md | 8 ++++---- contributor_docs/repo_structure.md | 2 +- contributor_docs/steward_guidelines.md | 14 +++++++------- 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/contributor_docs/README.md b/contributor_docs/README.md index a03bc54fcd..4d69c6efdf 100644 --- a/contributor_docs/README.md +++ b/contributor_docs/README.md @@ -4,7 +4,7 @@ Thanks for your interest in contributing to p5.js! Our community values contribu This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. We use the @all-contributors bot to handle adding people to the README.md file. You can ask @all-contributors bot to add you in an issue or PR comment like so: ``` -@all-contributors please add @[your github handle] for [your contribution type] +@all-contributors please add @[your GitHub handle] for [your contribution type] ``` You can find relevant contribution type [here](https://allcontributors.org/docs/en/emoji-key). Although we will usually automatically add you to the contributor list using the bot after merging your PR. The contributor docs are published on p5.js [website](https://p5js.org/contributor-docs/#/), and hosted on p5.js [GitHub repository](https://github.com/processing/p5.js/tree/main/contributor_docs). diff --git a/contributor_docs/contributing_documentation.md b/contributor_docs/contributing_documentation.md index 361322ab62..3ec2d4e613 100644 --- a/contributor_docs/contributing_documentation.md +++ b/contributor_docs/contributing_documentation.md @@ -31,6 +31,6 @@ While the examples in the reference are meant to be very simplistic snippets of ## 👉 Getting started * Read the [p5.js community statement](http://p5js.org/community/) * Optional: Check out the [contributor docs](./README.md) to get an overview of the repository and learn how to build the code (if relevant for you). -* All discussion happens on github issues, so there's no slack/gitter/etc channel you need to join. +* All discussion happens on GitHub issues, so there's no slack/gitter/etc channel you need to join. * Add your name to the [contributors list](https://github.com/processing/p5.js#contributors) in the readme.md file! Instructions [here](https://github.com/processing/p5.js/issues/2309). * And of course, if you're more of a bug fixer kind of person, feel free to jump into any of the [issues](https://github.com/processing/p5.js/issues)! diff --git a/contributor_docs/contributor_guidelines.md b/contributor_docs/contributor_guidelines.md index 3cdb7376ce..de222836fb 100644 --- a/contributor_docs/contributor_guidelines.md +++ b/contributor_docs/contributor_guidelines.md @@ -14,7 +14,7 @@ This is a fairly long and comprehensive document but we will try to deliniate al - [New Feature Request](#new-feature-request) - [Discussion](#discussion) - [Working on p5.js codebase](#working-on-p5js-codebase) - - [Using the Github edit functionality](#using-the-github-edit-functionality) + - [Using the GitHub edit functionality](#using-the-github-edit-functionality) - [Forking p5.js and working from your fork](#forking-p5js-and-working-from-your-fork) - [Codebase breakdown](#codebase-breakdown) - [Build setup](#build-setup) @@ -34,14 +34,14 @@ This is a fairly long and comprehensive document but we will try to deliniate al --- # All about issues -The majority of the activity on p5.js' Github repositories (repo for short) happens in issues and issues will most likely be the place to start your contribution process as well. +The majority of the activity on p5.js' GitHub repositories (repo for short) happens in issues and issues will most likely be the place to start your contribution process as well. ## What are issues? -Issue is the generic name for a post on Github that aims to describe, well, an issue. This "issue" can be a bug report, a request to add new feature, a discussion, a question, an announcement, or anything that works as a post. Comments can be added below each issue by anyone with a Github account, including bots! It is the place where contributors dicusses topics related to the development of the project in the repo. +Issue is the generic name for a post on GitHub that aims to describe, well, an issue. This "issue" can be a bug report, a request to add new feature, a discussion, a question, an announcement, or anything that works as a post. Comments can be added below each issue by anyone with a GitHub account, including bots! It is the place where contributors dicusses topics related to the development of the project in the repo. While an issue can be opened for a wide variety of reasons, for p5.js' repos we usually only use issues to discuss p5.js source code development related topics. Topics such as debugging your own code, inviting collaborators to your project, or other unrelated topics should be discuss either on the [forum](https://discourse.processing.com) or on other platforms. -We have created easy to use issue templates to aid you in deciding whether a topic should be a Github issue or it should be posted somewhere else! +We have created easy to use issue templates to aid you in deciding whether a topic should be a GitHub issue or it should be posted somewhere else! ## Issue templates p5.js' issue templates not only makes it easier for stewards and maintainers to understand and review issues, it also makes it simpler for you to file the relevant issue and receive a reply faster. Although they are called templates, from your perspective, it will just be like filling in a simple form where all the different fields of the form are the potentially important information that issue reviewers will need to properly diagnose your issue. @@ -92,13 +92,13 @@ Similarly, if you have come across an issue or joined in discussions of an issue You should not "jump the queue" by filing a PR for an issue that either someone else has indicated willingness to submit a contribution or has already been assigned to someone else. We will always prioritise "first assigned first serve" order for accepting code contribution for an issue, if you file a PR for an issue while someone else is still working on the same issue, your PR will be closed. If you see that it has been a few months since last activity on an issue with an assigned individual, you can check in with them by leaving a polite comment on the issue asking for progress and if they need help with the implementation. We generally allow for fairly long time frame for people to work on their contributions as we understand that most people will often be working on a volunteer basis or it simply takes more time for them to work on the feature; similarly, you should work at your own pace and be confident that there is no hard time limit on how long you can spend working on something. That being said, if you are having trouble with any aspect of your code contribution, do not hesitate to ask for help in the issue, the stewards and maintainers, as well as members of our community, will do their best to guide you! -## Using the Github edit functionality -When viewing a file on the Github web interface, near the top of the content of the file you are viewing will be a pencil icon button. This button is a convenient edit feature provided by Github that simplifies many of the processes we will be covering below and can be used to make quick and simple edits to the file you are viewing. +## Using the GitHub edit functionality +When viewing a file on the GitHub web interface, near the top of the content of the file you are viewing will be a pencil icon button. This button is a convenient edit feature provided by GitHub that simplifies many of the processes we will be covering below and can be used to make quick and simple edits to the file you are viewing. However, it is not recommended to use this feature other than for very simple changes. One of the main reason for this is that for more complex changes to the source code, it should be built and tested locally before being filed as a PR. Using a local development environment is also often much more fluent for most as compared to the basic editing environment provided by this edit functionality. ## Forking p5.js and working from your fork -The first step is to fork the p5.js repository. Forking has a specific meaning in open source but for our purpose it means creating a copy of the repository and storing it in your own Github account. To fork a repo, simply click on the "Fork" button near the top of the page and Github will make a copy of the repo in your account. +The first step is to fork the p5.js repository. Forking has a specific meaning in open source but for our purpose it means creating a copy of the repository and storing it in your own GitHub account. To fork a repo, simply click on the "Fork" button near the top of the page and GitHub will make a copy of the repo in your account. Working from your fork of the p5.js repository is necessary because you will likely not have direct write access to the official p5.js repository and working on a fork allows you to make changes and later submit them back to the official repository. diff --git a/contributor_docs/release_process.md b/contributor_docs/release_process.md index a93e2e0553..bad0955221 100644 --- a/contributor_docs/release_process.md +++ b/contributor_docs/release_process.md @@ -22,7 +22,7 @@ $ npm version [major|minor|patch] # Choose the appropriate version tag $ git push origin main $ git push origin v1.4.2 # Replace the version number with the one just created above ``` -The actual release steps are all run on Github Actions CI. +The actual release steps are all run on GitHub Actions CI. ## Monitor and check results Once the above commands have been executed, the build and release action can be monitored from the ["Actions" tab](https://github.com/processing/p5.js/actions) on the p5.js GitHub repo page (look for a job that says "New p5.js release"), clicking into the job can give a more detailed job log of what's running. @@ -38,13 +38,13 @@ CDNs will take a bit more time (a day or two) to update but they will automatica --- ## What's actually happening -The Github Action ["New p5.js release"](../.github/workflows/release.yml) is triggered on a tag that matches the pattern `v*.*.*` which is created by the `npm version ___` command. +The GitHub Action ["New p5.js release"](../.github/workflows/release.yml) is triggered on a tag that matches the pattern `v*.*.*` which is created by the `npm version ___` command. Once triggered, it will run the following steps: 1. Clone the repository, setup node.js, extract version number, install dependencies with `npm`, and run test with `npm test`. -2. Create the release files that will be uploaded to Github releases. -3. Create a release on Github and publish latest version on NPM. +2. Create the release files that will be uploaded to GitHub releases. +3. Create a release on GitHub and publish latest version on NPM. 4. Update website files 1. Clone the website repository 2. Copy `data.json` and `data.min.json` to the right location diff --git a/contributor_docs/repo_structure.md b/contributor_docs/repo_structure.md index 2f12eb6690..3aff5a84d5 100644 --- a/contributor_docs/repo_structure.md +++ b/contributor_docs/repo_structure.md @@ -15,7 +15,7 @@ There are a lot of files here! Here's a brief overview. It can be confusing, but - 📁`contributor_docs/` contains documents that explain practices and principles for contributors - 📁`docs/` does not actually contain docs! Rather, it contains the code used to *generate* the [online reference manual](https://p5js.org/reference/). -- 📁`lib/` contains an empty example and the p5.sound add-on, which is periodically updated via pull request from the [p5.js-sound repository](https://github.com/processing/p5.js-sound). This is also where the built p5.js library gets placed after being compiled to a single file using [Grunt](https://gruntjs.com/). It does not need to be checked into the github repository when you make a pull request. +- 📁`lib/` contains an empty example and the p5.sound add-on, which is periodically updated via pull request from the [p5.js-sound repository](https://github.com/processing/p5.js-sound). This is also where the built p5.js library gets placed after being compiled to a single file using [Grunt](https://gruntjs.com/). It does not need to be checked into the gitHub repository when you make a pull request. - 📁`src/` contains all the source code for the library, which is topically organized into separated modules. This is what you'll work on if you are changing p5.js. Most folders have their own readme.md files inside to help you find your way around. - 📁`tasks/` contains scripts which perform automated tasks related to the build, deployment, and release of new versions of p5.js. - 📁`tests/` contains unit tests which ensure the library continues to function correctly as changes are made. diff --git a/contributor_docs/steward_guidelines.md b/contributor_docs/steward_guidelines.md index 0d96c73974..45d8f9bd0b 100644 --- a/contributor_docs/steward_guidelines.md +++ b/contributor_docs/steward_guidelines.md @@ -18,13 +18,13 @@ Whether you have just joined us as a steward, a seasoned maintainer of p5.js, or - [Release Process](#release-process) - [Tips & Tricks](#tips--tricks) - [Reply templates](#reply-templates) - - [Github CLI](#github-cli) + - [GitHub CLI](#github-cli) - [Managing notifications](#managing-notifications) --- # Issues -We encourage most source code contributions to start with an issue and as such issues are the place where most of the discussions will take place. The steps you can take when reviewing an issue will depend on what kind of issue it is. The repo uses [Github issue templates](../.github/ISSUE_TEMPLATE) in order to better organize different kinds of issues and encourage issue author to provide all relevant information about their problem. The first step in reviewing the issue will often be looking through the filled out template and determine if you need additional information (either because some fields weren't filled in or the incorrect template was used). +We encourage most source code contributions to start with an issue and as such issues are the place where most of the discussions will take place. The steps you can take when reviewing an issue will depend on what kind of issue it is. The repo uses [GitHub issue templates](../.github/ISSUE_TEMPLATE) in order to better organize different kinds of issues and encourage issue author to provide all relevant information about their problem. The first step in reviewing the issue will often be looking through the filled out template and determine if you need additional information (either because some fields weren't filled in or the incorrect template was used). ## Bug report For bug report issues, they should be using the "Found a bug" issue template. @@ -84,7 +84,7 @@ For feature enhancement issues, they should be using the "Existing Feature Enhan This type of issue has a minimal template ("Discussion") and should be use only if a particular discussion doesn't fall under the other three existing templates or be better suited to the forum or Discord. - If an issue is opened as a discussion but should be, for example, a bug report, the correct labeled should be applied and the "discussion" label removed. Additional info about the bug should also be requested from the author if not already included (following [Bug report](#bug-report)) above. -- If an issue is opened as a discussion but isn't relevant to source code contribution or otherwise relevant to the Github repositories/contribution process/contribution community (eg. a discussion about the best kind of projector to use for an exhibition showing sketches done with p5.js), they should be redirected to the forum or Discord and the issue closed. +- If an issue is opened as a discussion but isn't relevant to source code contribution or otherwise relevant to the GitHub repositories/contribution process/contribution community (eg. a discussion about the best kind of projector to use for an exhibition showing sketches done with p5.js), they should be redirected to the forum or Discord and the issue closed. - If relevant, additional labels should be added to discussion issues to further signal what type of discussion it is at a glance. --- @@ -104,7 +104,7 @@ Simple fix such as small typo fix can be merged directly by anyone with merge ac ## Bug fix 1. Bug fixes should be reviewed by the relevant area steward, ideally the same one that approved the referenced issue for fixing. 2. The PR "Files Changed" tab can be used to initially review whether the fix is as described in the discussion in the issue. -3. The PR should be tested locally whenever possible and relevant. The Github CLI can be helpful in streamlining some of the process. (See more below in [Tips & Tricks](#tips-tricks)). +3. The PR should be tested locally whenever possible and relevant. The GitHub CLI can be helpful in streamlining some of the process. (See more below in [Tips & Tricks](#tips-tricks)). - The fix should address the original issue sufficiently - The fix should not change any existing behaviours unless agreed upon in the original issue - The fix should not have significant performance impact on p5.js @@ -118,7 +118,7 @@ Simple fix such as small typo fix can be merged directly by anyone with merge ac 5. Once the PR has been reviewed and no additional changes are required, a steward can mark the PR as "Approved" by choosing the "Approve" option in the previous step (instead of "Comment" or "Request changes") with or without additional comments. The steward can then either request additional review by another steward or maintainer if desired, or merge the PR if they have merge access or a maintainer will merge the approved PR. 6. @all-contributors bot should be called to add any new contributors to the list of contributors in the README.md file. ``` -@all-contributors please add @[github handle] for [contribution type] +@all-contributors please add @[GitHub handle] for [contribution type] ``` ## New feature/feature enhancement @@ -253,7 +253,7 @@ Below are some of the Saved Replies that are being used by p5.js maintainers, yo > I'm closing this for organizational purposes. Please reopen if you can provide a code snippet that illustrates the issue. Thanks! #### Closing: Use the Forum! -> The github issues here are a good place for bugs and issues with the p5.js library itself. for questions about writing your own code, tests, or following tutorials, the [forum](https://discourse.processing.org/) is the best place to post. Thanks! +> The GitHub issues here are a good place for bugs and issues with the p5.js library itself. for questions about writing your own code, tests, or following tutorials, the [forum](https://discourse.processing.org/) is the best place to post. Thanks! #### Closing: GSOC > Thanks! The best place to discuss GSOC proposals is on our [forum](https://discourse.processing.org/c/summer-of-code). @@ -275,7 +275,7 @@ You can go ahead with a fix. Thanks. #### Merged PR Looks good. Thanks! -## Github CLI +## GitHub CLI Reviewing a complex PR can be difficult with seemingly arcane git commands required to get the PR's version of code locally for you to test. Fortunately the [GitHub CLI](https://cli.github.com/) tool can help greatly with this process and more. After installing the CLI and logging in, reviewing a PR locally can be done by just running the command `gh pr checkout [pull_request_id]` and the process of fetching remote fork, creating a branch, and checking out the branch are all done automatically for you. Going back to the main branch will just be the same as switching a branch by running `git checkout main`. You can even leave a comment in the PR from the CLI without needing to visit the webpage at all! From cc98b93f06a63888ce183e391b371c7a9d039428 Mon Sep 17 00:00:00 2001 From: Qianqian Ye Date: Tue, 25 Jul 2023 11:31:09 -0700 Subject: [PATCH 2/2] Fix 'gitHub' typo --- contributor_docs/repo_structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributor_docs/repo_structure.md b/contributor_docs/repo_structure.md index 3aff5a84d5..27ce5dff92 100644 --- a/contributor_docs/repo_structure.md +++ b/contributor_docs/repo_structure.md @@ -15,7 +15,7 @@ There are a lot of files here! Here's a brief overview. It can be confusing, but - 📁`contributor_docs/` contains documents that explain practices and principles for contributors - 📁`docs/` does not actually contain docs! Rather, it contains the code used to *generate* the [online reference manual](https://p5js.org/reference/). -- 📁`lib/` contains an empty example and the p5.sound add-on, which is periodically updated via pull request from the [p5.js-sound repository](https://github.com/processing/p5.js-sound). This is also where the built p5.js library gets placed after being compiled to a single file using [Grunt](https://gruntjs.com/). It does not need to be checked into the gitHub repository when you make a pull request. +- 📁`lib/` contains an empty example and the p5.sound add-on, which is periodically updated via pull request from the [p5.js-sound repository](https://github.com/processing/p5.js-sound). This is also where the built p5.js library gets placed after being compiled to a single file using [Grunt](https://gruntjs.com/). It does not need to be checked into the GitHub repository when you make a pull request. - 📁`src/` contains all the source code for the library, which is topically organized into separated modules. This is what you'll work on if you are changing p5.js. Most folders have their own readme.md files inside to help you find your way around. - 📁`tasks/` contains scripts which perform automated tasks related to the build, deployment, and release of new versions of p5.js. - 📁`tests/` contains unit tests which ensure the library continues to function correctly as changes are made.