Meta:Contributing/Code

While most of our work is informative, the Community Management Community does sometimes need to design its own tools, and other pieces of software needed to keep things running smoothly. You can find our open-source projects on Codeberg and GitHub, though please note that we intend to fully migrate from GitHub to Codeberg in the future.

Tooling

All of our projects use Git for version control, a tool we expect you to have a working understanding of before you get started. Ideally, you'll also have commit signing set up, using either an SSH key or a GPG key that you keep as secure as possible.

Aside from this, you're welcome to use whatever code editors and assistance tools you like, as long as they aren't generative AI tools, and aren't otherwise disruptive. This applies regardless of whether the processing is done locally or in the cloud. Examples of banned tools include:

• Integrated and standalone full-scale code generators, including LLMs like Claude or ChatGPT, integrated generation tools like Copilot or Junie, and other tools like them.
• AI video, audio and image generators, including Sora, MakeSong, Midjourney, and other tools like them.
• AI text generators, including ChatGPT, Gemini, Perplexity, Meta AI, and other tools like them.
• Code formatters, aside from the ones we recommend in a project's documentation and files, and JetBrains' formatting plugins.
  • To be more specific, we will deny all contributions that reformat any code that is unrelated to the contribution.

We make exceptions for the following AI-based tools, as no reasonable replacements exist, and they significantly improve contributions:

• LanguageTool and JetBrains Grazie, both of which are important spelling and grammar checkers, and help to keep your writing clean and readable. If you need to pick between them, we strongly recommend LanguageTool.
• Single-line completion tools in your IDE, such as the automatic completion provided in IntelliJ IDEA, as long as those tools don't accept any form of prompt as an input.

If you've already used a banned tool to create a contribution before reading this section, contact us immediately.

Workflow

• Before you start working on a project, please check its issues and pull requests, and quickly search our Discord server, to make sure you're not duplicating someone else's work.
  • If someone else is already working on your idea, consider getting in touch to see how you can help.
  • If you've determined that nobody else is already working on your idea, contact us by creating an issue on the project's repository, and we'll discuss it with you.
• Once your idea is approved, fork the repository and create a new branch to work in. Creating a new branch is essential, as it makes it easier for you to pull in changes from upstream later if you end up needing to.
• Start working on your contribution, taking care to write modular, maintainable, and readable code, and avoiding any generative AI tools that we haven't specified as allowed above. Remember to test your changes, making sure they don't break existing features, and writing unit tests as appropriate.
• Open a Pull Request as early as possible — ideally after you've pushed your first commit — and mark it as a draft if it's not yet ready to be merged. This makes it easier for us to leave feedback as you work, potentially resulting in less work for you later on.
• Mark your Pull Request as ready for review once you feel your contribution is ready. Keep an eye on the Pull Request, and remember to address and respond to any reviews and comments you get there.
• Once your contribution is ready, and you've addressed all of our feedback, we'll merge it. At this point, you've finished your contribution — congratulations!

Code Style

We provide a .editorconfig file with all of our projects, which defines our baseline code formatting expectations. Most editors either include support for this or have some kind of plugin available, so it's important to double-check that first.

Generally speaking, we expect you to follow the style already established by the project's existing code. We also encourage you to use any linters and formatters we provide a configuration for, especially since we'll be running them in CI when you submit your Pull Request.

Otherwise, keep the following points in mind:

• Use tabs instead of spaces where possible and realistic. This makes your code more accessible for blind and visually impaired developers, including those using massive fonts and Braille displays — especially where editors don't include great accessibility tools.
• Don't play code golf. Instead, use longer forms of statements where they're more readable than the shorter versions, and provide plenty of blank lines between different types of statements.
• Alphabetise where possible. Sorting lists alphabetically often makes things easier to read. It is also helpful to alphabetise lists when creating written, non-code content, as it shows readers that you didn't order the list by your (or our) preference.
• Consistent code is preferred over perfect code. It is important to be aware of the limitations of your tooling and programming languages, and it will sometimes be impossible to write code that keeps your linters happy. In those situations, it is essential to focus on functionality and readability, rather than bending over backwards to meet what the linters demand of you.