|
1 | | -# Contributing to the p5.js Web Editor |
| 1 | +# Contributing to the p5.js Editor 📖 🐛 🎨 |
2 | 2 |
|
3 | | -Hello! We welcome community contributions to the p5.js Web Editor. Contributing takes many forms and doesn't have to be **writing code**, it can be **reporting bugs**, **proposing new features**, **creating UI/UX designs**, and **updating documentation**. |
| 3 | +Welcome to the Contributor Guidelines! |
| 4 | + |
| 5 | +This document is for anyone interested in contributing to the p5.js Editor—whether you're new to open source, refreshing your memory on some technical steps, or curious about how the codebase works! |
| 6 | + |
| 7 | +We believe that anyone can be a contributor; you don’t need to be an expert. We also know that not everyone has the same time, energy, or resources to spend, and that’s okay. We’re just glad you’re here! |
| 8 | + |
| 9 | +This guide has been adapted from the Contributor Guidelines within the [Processing](https://github.com/processing/processing4/blob/main/CONTRIBUTING.md) and [p5.js](https://github.com/processing/p5.js/blob/main/contributor_docs/contributor_guidelines.md) repositories. They're full of helpful and in-depth resources—please check them out! |
| 10 | + |
| 11 | +If you haven't already, read our [Community and Statement Code of Conduct](https://editor.p5js.org/code-of-conduct) to understand the values that guide our community and how to participate respectfully and constructively. |
4 | 12 |
|
5 | 13 | ## Table of Contents |
6 | | -- [Contributing to the p5.js Web Editor](#contributing-to-the-p5js-web-editor) |
7 | | - - [Table of Contents](#table-of-contents) |
8 | | - - [Code of Conduct](#code-of-conduct) |
9 | | - - [How Can I Contribute?](#how-can-i-contribute) |
10 | | - - [First Steps](#first-steps) |
11 | | - - [Good First Issues](#good-first-issues) |
12 | | - - [Good Medium Issues](#good-medium-issues) |
13 | | - - [Project Board](#project-board) |
14 | | - - [Project Ideas](#project-ideas) |
15 | | - - [Issue Search and Tagging](#issue-search-and-tagging) |
16 | | - - [Beginning Work](#beginning-work) |
17 | | - - [Contribution Guides](#contribution-guides) |
18 | | - |
19 | | -## Code of Conduct |
20 | | - |
21 | | -Please follow the guidelines in the [Code of Conduct](https://github.com/processing/p5.js-web-editor/blob/develop/.github/CODE_OF_CONDUCT.md). |
| 14 | +- [About Github](#about-github) |
| 15 | +- [How Can I Contribute?](#how-can-i-contribute) |
| 16 | +- [Working Within the Codebase](#working-within-the-codebase) |
| 17 | +- [Ideas for Getting Started](#ideas-for-getting-started) |
| 18 | + |
| 19 | +## About Github |
| 20 | +The p5.js Editor’s codebase is hosted on [GitHub](https://github.com/processing). GitHub is a website where people can collaborate on code. It’s widely used for open source projects and makes it easier to keep track of changes, report issues with the software, and contribute improvements to the code. |
| 21 | + |
| 22 | +If you're new to GitHub, a good place to start is the [First Contribution's tutorial guide](https://github.com/firstcontributions/first-contributions/blob/main/docs/gui-tool-tutorials/github-desktop-tutorial.md), which walks you through the basics of contributing to a project using GitHub Desktop. For more information, we recommend [Git and GitHub for Poets](https://www.youtube.com/playlist?list=PLRqwX-V7Uu6ZF9C0YMKuns9sLDzK6zoiV), a beginner-friendly video series. |
| 23 | + |
| 24 | +The [Hello World](https://guides.github.com/activities/hello-world/) and [Forking](https://guides.github.com/activities/forking/) Guides from Github are also great acitivities for exercising how you might want to use these tools and features. |
22 | 25 |
|
23 | 26 | ## How Can I Contribute? |
24 | | -If you're new to open source, [read about how to contribute to open source](https://opensource.guide/how-to-contribute/). |
| 27 | +If you're new to open source, start by reading [this beginner-friendly guide about contributing to an open source project](https://opensource.guide/how-to-contribute/). It covers why you might want to contribute to a project, what it means to contribute, and how to navigate certain aspects of the contribution process. |
25 | 28 |
|
26 | 29 | ### First Steps |
27 | | -Don't know where to begin? Here are some suggestions to get started: |
28 | | -* Think about what you're hoping to learn by working on open source. The web editor is a full-stack web application, therefore there's tons of different areas to focus on: |
29 | | - - UI/UX design |
30 | | - - Project management: Organizing tickets, pull requests, tasks |
31 | | - - Front end: React/Redux, CSS/Sass, CodeMirror |
32 | | - - Back end: Node, Express, MongoDB, Jest, AWS |
33 | | - - DevOps: Travis CI, Jest, Docker, Kubernetes, AWS |
34 | | - - Documentation |
35 | | - - Translations: Application and documentation |
36 | | -* Use the [p5.js Web Editor](https://editor.p5js.org)! Find a bug? Think of something you think would add to the project? Open an issue. |
37 | | -* Expand an existing issue. Sometimes issues are missing steps to reproduce, or need suggestions for potential solutions. Sometimes they need another voice saying, "this is really important!" |
38 | | -* Try getting the project running locally on your computer by following the [installation steps](./../contributor_docs/installation.md). |
39 | | -* Look through the documentation in the [developer docs](../contributor_docs/). Is there anything that could be expanded? Is there anything missing? |
40 | | -* Look at the [development guide](./../contributor_docs/development.md). |
| 30 | +As you start navigating the p5.js editor and the codebase, you may want to think about what you're hoping to learn by working on open source project. The p5.js editor is a full-stack web application, therefore there's tons of different areas that you could focus on. Some of them can look like: |
| 31 | + |
| 32 | + - **Translation** – Help localize the software and documentation in your language. Many of us made our first contribution this way. |
| 33 | + - **Testing** – Try out new releases and report bugs. |
| 34 | + - **Documentation** – Improve tutorials, reference pages, or even this guide! |
| 35 | + - **Design** – Contribute UI design ideas or help improve user experience. |
| 36 | + - **Project Management** - Organizing tickets, pull requests, and tasks. |
| 37 | + - **Front-End Development** - We use React/Redux, CSS/Sass, and CodeMirror. |
| 38 | + - **Back-End Development** - We use Node, Express, MongoDB, Jest, and AWS. |
| 39 | + - **DevOps** - Some tools we use are Travis CI, Jest, Docker, Kubernetes, and AWS. |
| 40 | + - **Community Support** – Answer questions on the forum. |
| 41 | + - **Education** – Create learning resources, curriculums, organize workshops, or share your teaching experiences. |
| 42 | + - **Art and Projects** – Share what you’re making with p5.js or the p5.js Editor! |
| 43 | + - **Outreach and Advocacy** – Help others discover and get excited about the project. |
| 44 | + |
| 45 | +Once you've found something you're excited to contribute to, reference the relevant guides and documentation to make sure you're following the recommended process. |
| 46 | + |
| 47 | +## Working Within the Codebase |
| 48 | + |
| 49 | +### Making Your First Contribution |
| 50 | +Issues with these labels are a great place to start! |
| 51 | +- [Help Wanted](https://github.com/processing/p5.js-web-editor/labels/Help%20Wanted) |
| 52 | +- [Good First Issue](https://github.com/processing/p5.js-web-editor/labels/Good%20First%20Issue) |
| 53 | +- [Need Steps to Reproduce](https://github.com/processing/p5.js-web-editor/labels/Needs%20Steps%20to%20Reproduce) |
| 54 | +- [Ready for Work](https://github.com/processing/p5.js-web-editor/labels/Ready%20for%20Work) |
41 | 55 |
|
42 | | -### Good First Issues |
43 | | -For first-time contributors or those who want to start with a small task, [check out the list of good first issues](https://github.com/processing/p5.js-web-editor/labels/good%20first%20issue), or [issues that need documentation of steps to reproduce](https://github.com/processing/p5.js-web-editor/issues?q=is%3Aissue+is%3Aopen+label%3A%22needs+steps+to+reproduce%22). If the issue has not been assigned to anyone, then you can work on it! It's okay to not know how to fix an issue, and feel free to ask questions about to approach the problem! We are all here to learn and make something awesome. Someone from the community would help you out and these are great issues for learning about the web editor, its file structure and its development process. |
| 56 | +A breakdown of what each label means can be found in the [Preparing an Issue Guide](#preparing-an-issue). |
44 | 57 |
|
45 | | -### Good Medium Issues |
46 | | -If you're looking for a bigger project to take on, look through the issues tagged [good medium issue](https://github.com/processing/p5.js-web-editor/labels/good%20medium%20issue). These issues are self-contained projects that may take longer to work on, but are great if you're looking to get more deeply involved in contributing! |
| 58 | +When approaching these issues, know that it's okay to not know how to fix an issue! Feel free to ask questions about to approach the problem. We are all here to learn and make something awesome. Someone from the community will help you out, and asking questions is a great way to learn about the p5.js editor, its file structure, and development process. |
47 | 59 |
|
48 | | -### Project Board |
49 | | -Many issues are related to each other and fall under bigger projects. To get a bigger picture, look at the [All Projects](https://github.com/processing/p5.js-web-editor/projects/) board. |
| 60 | +### Before You Start Working On An Issue |
| 61 | +Before beginning work on a code contribution, please make sure that: |
| 62 | +- The issue has been discussed and a proposed solution has been agreed upon. |
| 63 | +- You have been assigned to the issue. |
| 64 | +- If an implementation has been agreed upon but no one has volunteered to take it on, feel free to comment and offer to help. A maintainer can then assign the issue to you. |
50 | 65 |
|
51 | | -### Project Ideas |
52 | | -If you're looking for inspiration for Google Summer of Code or a bigger project, there's a [project list](https://github.com/processing/processing/wiki/Project-List#p5js-web-editor) maintained on the Processing wiki. |
| 66 | +### Choosing an Issue |
53 | 67 |
|
54 | | -### Issue Search and Tagging |
55 | | -If you're looking for issues to work on, a good place to start is with tickets labeled [high priority](https://github.com/processing/p5.js-web-editor/labels/priority%3Ahigh). You can also look for tickets that are [feature enhancements](https://github.com/processing/p5.js-web-editor/labels/type%3Afeature), [bug fixes](https://github.com/processing/p5.js-web-editor/labels/type%3Abug), and a few other tags. |
| 68 | +The best way to verify if an issue is ready to be worked on is checking if it has the [Ready for Work](https://github.com/processing/p5.js-web-editor/labels/Ready%20for%20Work) label. However, here are a few other suggestions to keep in mind as you explore the issues: |
56 | 69 |
|
57 | | -If you feel like an issue is tagged incorrectly (e.g. it's low priority and you think it should be high), please update the issue! |
| 70 | +- **Please do not open a pull request for an issue that is already assigned to someone else**. We follow a “first assigned, first served” approach to avoid duplicated work. If you open a PR for an issue that someone else is already working on, your PR will be closed. |
58 | 71 |
|
59 | | -### Beginning Work |
| 72 | +- If an issue has been inactive for a long time, you’re welcome to check in politely by commenting to see if the assignee still plans to work on it or would be open to someone else taking over. |
60 | 73 |
|
61 | | -If you'd like to work on an issue, please comment on it to let the maintainers know, so that they can assign it to you. If someone else has already commented and taken up that issue, please refrain from working on it and submitting a PR without asking the maintainers as it leads to unnecessary duplication of effort. |
| 74 | +- There’s no hard deadline for completing contributions. We understand that people often contribute on a volunteer basis and timelines may vary. That said, if you run into trouble or have questions at any point, don’t hesitate to ask for help in the issue thread. Maintainers and other community members are here to support you. |
62 | 75 |
|
63 | | -Then, look at the [development guide](https://github.com/processing/p5.js-web-editor/blob/develop/contributor_docs/development.md) for instructions on how to install the project locally and follow the right development workflow. |
| 76 | +### Before Submitting a Pull Request |
| 77 | +Before submitting a pull request, make sure that: |
| 78 | +- Your work is related to an issue. **Pull requests that do not have an associated issue will not be accepted.** |
| 79 | +- Your work adheres to the style guidelines and fits in with the rest of the codebase. |
| 80 | +- You ran the project locally and tested your changes. Pay special attention to any specific areas of the p5.js editor that may be affected by your changes. Does everything still work as before? Great! |
| 81 | +- You reference the [Preparing a Pull Request Guide](https://github.com/processing/p5.js-web-editor/blob/develop/contributor_docs/preparing_a_pull_request.md) for more details! |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Ideas for Getting Started |
| 86 | +* Use the [p5.js Editor](https://editor.p5js.org)! Find a bug? Think of something you think would add to the project? Reference the [Preparing an Issue Guide](#preparing-an-issue) and open an issue. |
| 87 | +* Expand an existing issue. Sometimes issues are missing steps to reproduce, or need suggestions for potential solutions. Sometimes they need another voice saying, "this is really important!" |
| 88 | +* Try getting the project running locally on your computer by following the [installation steps](./../contributor_docs/installation.md). |
| 89 | +* Look through the documentation in the [developer docs](../contributor_docs/) and the [development guide](./../contributor_docs/development.md). Is there anything that could be expanded? Is there anything missing? |
64 | 90 |
|
65 | | -### Contribution Guides |
66 | 91 |
|
67 | | -* [https://guides.github.com/activities/hello-world/](https://guides.github.com/activities/hello-world/) |
68 | | -* [https://guides.github.com/activities/forking/](https://guides.github.com/activities/forking/) |
|
0 commit comments