Welcome to the contributor guidelines!
This document is for new contributors looking to contribute code to Processing, contributors refreshing their memory on some technical steps, or anyone interested in working on Processing’s codebase. 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 on Processing. That’s okay. We’re glad you’re here!
Tip
For questions about your own sketches, or broader conversations about coding in Processing, our online forum is a fantastic resource (make sure to read the forum guidelines before posting). You can also visit the Processing Community Discord.
Processing’s codebase is hosted on GitHub. 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.
If you're new to GitHub, a good place to start is this tutorial guide, which walks you through the basics of contributing to a project using GitHub Desktop. For more information, we recommend Git and GitHub for Poets, a beginner-friendly video series by Dan Shiffman.
Most activity on Processing’s GitHub happens in issues. Issues are GitHub posts which can contain bug reports, feature requests, or broader discussions about the development of Processing. It’s a great place to begin contributing.
To file a new issue, visit the Issues tab on the repository and click New issue then select the most appropriate template and follow the included instructions. These templates help maintainers understand and respond to issues faster.
Note
Before opening a new issue, check our troubleshooting page. The answer may already be there.
To contribute to Processing, we recommend using GitHub Desktop and IntelliJ IDEA (Community Edition), as that’s the toolchain we’re best able to support. If you’re comfortable using Git on the command line or prefer a different editor, that’s totally fine too! Use what works best for you. Some familiarity with the command line can help, but it’s not required.
You'll need to set up a local development environment—see our build instructions to get started.
Most issues marked help wanted or good first issue are a good place to start.
Before beginning work on a code contribution, please make sure that:
- The issue has been discussed and a proposed solution has been approved.
- You have been assigned to the issue.
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.
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.
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.
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.
Keep the style guidelines in mind when making changes to the code. If you don’t, someone else will have to reformat your code so that it fits everything else (or we’ll have to reject your changes if it’ll take us too long to clean things up).
Before you contribute your changes, it's essential that you make sure that Processing still builds, runs, and functions on your machine. Here again, the build instructions are your best friend. Pay special attention to any features that may be affected by your changes. Does everything still work as before? Great!
Once your changes are ready:
- Push your branch to your fork
- Open a pull request from your branch into
mainon the official repository - Fill out the pull request information:
- Title: clear and descriptive
- Resolves: add
Resolves #[issue-number]if applicable - Changes: explain what you changed and why
- Tests: mention if you added tests or validated your changes
- Checklist: ensure tests pass and the branch is up-to-date
Maintainers usually review pull requests within one to two weeks. If changes are requested, follow up by pushing additional commits. The PR will automatically update.
If there hasn’t been any activity after two weeks, feel free to gently follow up. We kindly ask that you don’t request a review or tag maintainers before that time. Thanks for your patience!
Before opening a pull request, please make sure to discuss the related issue and get assigned to it first. This helps us stay aligned and avoid unnecessary work. Thank you!
In most cases, the best way to contribute a new feature is to create a library. The Processing Library Template is a great way to get started. For more instructions, see the library template documenation.
Nearly all new features are first introduced as a Library or a Mode, or even as an example. The current OpenGL renderer and Video library began as separate projects by Andrés Colubri, who needed a more performant, more sophisticated version of what we had in Processing for work that he was creating. The original loadShape() implementation came from the “Candy” library by Michael Chang (“mflux“). Similarly, Tweak Mode began as a separate project by Gal Sasson before being incorporated. PDE X was a Google Summer of code project by Manindra Moharana that updated the PDE to include basic refactoring and better error checking.
Developing features separately from the main software has several benefits:
- It’s easier for the contributor to develop the software without it needing to work for tens or hundreds of thousands of Processing users.
- It provides a way to get feedback on that code independently of everything else, and the ability to iterate on it rapidly.
- This feedback process also helps gauge the level of interest for the community, and how it should be prioritized for the software.
- We can delay the process of “normalizing” the features so that they’re consistent with the rest of Processing (function naming, structure, etc).
A major consideration for any new feature is the level of maintenance that it might require in the future. If the original maintainer loses interest over time (which is normal) and the feature breaks (which happens more often than we'd like), it sits on the issues list unfixed, which isn’t good for anyone.
Processing is a massive project that has existed for more than 20 years. Part of its longevity comes from the effort that’s gone into keeping things as simple as we can, and in particular, making a lot of difficult decisions about what to leave out. Adding a new feature always has to be weighed against the potential confusion of one more thing—whether it’s a menu item, a dialog box, a function that needs to be added to the reference, etc. Adding a new graphics function means making it work across all the renderers that we ship (Java2D, OpenGL, JavaFX, PDF, etc) and across platforms (macOS, Windows, Linux). Does the feature help enough people that it's worth making the reference longer? Or the additional burden of maintaining that feature? It's no fun to say “no,” especially to people volunteering their time, but we often have to.
The current Editor component is based on the ancient JEditSyntax package and has held up long past its expiration date. Exhaustive work has been done to look at replacing the component with something more modern, like RSyntaxArea, but that approach was considered too risky.
With Processing 4.4.0, we’ve started transitioning the Processing UI from Swing to Jetpack Compose Multiplatform, allowing us to replace Swing components gradually, without a full rewrite. Any work on updating the PDE and adding new features should focus on this migration. Replacing JEditSyntax will likely be the last step in the process. In the meantime, the editor does what it needs to do, for the intended audience. Features like code-folding, refactoring, or symbol navigation are currently out of scope.
For users who want editor features beyond what the PDE offers, we’re working to make Processing easier to use in other environments. Migrating the Processing CLI to Gradle and better Language Server support will help make that possible. This should reduce the pressure to add these features to the PDE itself, allowing it to stay focused on being a minimal, beginner-friendly coding sketchbook. If you'd like to help, let us know!
Refactoring is fun! There’s always more cleaning to do. It’s also often not very helpful.
Broadly speaking, the code is built the way it is for a reason. There are so many things that can be improved, but those improvements need to come from an understanding of what’s been built so far. Changes that include refactoring are typically only accepted from contributors who have an established record of working on the code. With a better understanding of the software, the refactoring decisions come from a better, more useful place.
The Processing project follows the all-contributors specification, recognizing all types of contributions, not just code. We use the @all-contributors bot to handle adding people to the README.md file. You can ask the @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]
We usually add contributors automatically after merging a PR, but feel free to request addition yourself by commenting on this issue.
We're always grateful for your help fixing bugs and implementing new features BUT You don’t have to write code to contribute to Processing! Here are just a few other ways to get involved:
- Translation – Help localize the software and documentation in your language. Many of us made our first contribution this way.
- Testing – Try out new releases (especially the betas) and report bugs.
- Documentation – Improve tutorials, reference pages, or even this guide!
- Design – Contribute UI design ideas or help improve user experience.
- Community Support – Answer questions on the forum.
- Education – Create learning resources, curriculums, organize workshops, or share your teaching experiences.
- Art and Projects – Share what you’re making with Processing and use the #BuiltWithProcessing hashtag 💙
- Outreach and Advocacy – Help others discover and get excited about the project.