Discourse Development Contributor Guidelines

Environment

Before you begin hacking on Discourse, you need to set yourself up with a good development environment.

Check out the appropriate guide for your platform:

All Platforms

Mac OS X

Linux (Ubuntu)

Windows

Knowing where to begin

Discourse is a big project and it assumes a certain level of comfort with its underlying technologies such as Ruby and JavaScript. Figuring out exactly how much extracurricular learning you need to do before getting started on Discourse proper can be hard. Luckily there’s a guide for that!

Plugins

Plugins are a great way get the know the Discourse internals in bite-sized portions. It’s also the gentlest way to start contributing code, because plugins don’t need to adhere to the narrow scope of the Discourse core.

Start here:

Also check out the very helpful Plugin outlet locations theme component.

Need some ideas on what to build? Just have a look through the popular ideas in #feature, #plugin:extras and the “Most awesome plugin for Discourse” topic (summarize it to see popular suggestions).

Contributing to Core

Contributing to Discourse core, i.e. github/discourse/discourse, involves a bit more process.

Signing the CLA

Firstly, anyone wishing to contribute to the Discourse repository MUST read & sign the Electronic Discourse Forums Contribution License Agreement. The Discourse team is legally prevented from accepting any pull requests from users who have not signed the CLA first.

Warming up with starter tasks

Browse the #starter-task tag for a list of low-complexity tasks to get you started.

Work through the bugs list

We have an ordered list of bugs at: bug - Discourse Meta.

Pick a bug, any bug, and get it fixed.

If you are going to take more than a few hours to fix it and submit a pull request, leave a note on the bug explaining you are working on it.

Help flesh out “Feature” topics

There are many open feature requests that need additional detail and team approval to be added to the product. feature - Discourse Meta feel free to participate on these topics. Adding additional details to the request, creating visual mockups, etc is super helpful!

Just keep in mind that not every feature is destined to be in core:

Improve performance

At Discourse we believe performance is a feature. We welcome pull requests that improve either client or server side performance.

Be sure to focus on high impact areas, like initial load of front page, or topic view. Improving performance for a background process that is triggered monthly is usually not a priority.

Improve Discourse maintained projects

Discourse maintains a large number of open source projects, they are consumed by Discourse. If for any reason you do not feel like signing a CLA (or wish to contribute to a non-GPL project) there are plenty of MIT options:


Conventions

Naming is CRITICAL

We strive to have 100% parity between names of objects discussed on the site and names of classes and columns in the database.

For example: we use the term post to describe posts on a topic. It follows that there is a “posts” table with the column “topic_id”. If for any reason we decided to call “topics” say “threads”, every instance of the word topic in the codebase and would have to be renamed to thread.

Compatibility with latest versions of dependant libraries is CRITICAL

We strive to ship Discourse with the up to date dependencies. This means we ship with the latest stable version of Rails, Ruby, Ember and so on.

We welcome contributions that help update dependencies to the latest stable. However be sure to test for regressions.

Test only contributions are welcome :thumbsup:

We welcome “test only” contributions, however be sure to focus on the right areas:

  1. A process that is untested is very high priority. (For example, testing the sign-in workflow)
  2. A controller action that has no testing is high priority. We strive to have a stable API, to achieve we need to ensure all controllers are tested.
  3. Mocking is heavily discouraged. Only use mocking when absolutely critical.

Refactoring only NOT welcome :thumbsdown:

It is often tempting to submit PRs that improve code climate score or amend internal logic to make it more readable.

Though we strive to have well factored code that is easy to reason about we can not afford risking regressions on a production product without immediate tangible gain. In the past we have suffered many regressions due to refactoring PRs.

If you wish to improve an area of the code, fix a bug in that area and also improve the code, or implement a feature and also improve the code.

Contributing code on GitHub

“…in 10 easy steps!”

1) Clone the Repo:

git clone git://github.com/discourse/discourse.git

2) Create a new Branch:

cd discourse
git checkout -b new_discourse_branch

Please keep your code clean: one feature or bug-fix per branch. If you find another bug, you want to fix while being in a new branch, please fix it in a separated branch instead.

3) Code

  • Adhere to common conventions you see in the existing code
  • Include tests, and ensure they pass
  • Search to see if your new functionality has been discussed on the Discourse meta forum, and include updates as appropriate.

4) Follow the Coding Conventions

  • two spaces, no tabs
  • no trailing whitespaces, blank lines should have no spaces
  • use spaces around operators, after commas, colons, semicolons, around { and before }
  • no space after (, [ or before ], )
  • use Ruby 1.9 hash syntax: prefer { a: 1 } over { :a => 1 }
  • prefer class << self; def method; end over def self.method for class methods
  • prefer { ... } over do ... end for single-line blocks, avoid using { ... } for multi-line blocks
  • avoid return when not required

Remember: We don’t accept pull requests consisting entirely of style changes. Style changes in the context of pull requests that also refactor code, fix bugs, improve functionality are welcome.

5) Commit

For every commit please write a short (max 72 characters) summary in the first line followed with a blank line and then more detailed descriptions of the change. Use markdown syntax for simple styling.

Don’t forget a prefix! Be sure to follow the GitHub commit prefix convention for your commit title.

NEVER leave the commit message blank! Provide a detailed, clear, and complete description of your commit! See “How to write a Git commit message” for great pointers.

5a) Linting

We lint our JavaScript code with eslint as well as following the formatting conventions of prettier, and we lint our ruby code with rubocop. All of these checks are run automatically in GitHub actions whenever you create a pull request for Discourse.

It is strongly recommended that you install our pre-commit git hooks using lefthook. This will run automatically every time you make a commit in Discourse core, and raise issues with the various languages and templates before you push them up and have to wait for GitHub CI to run. From project root:

mkdir .git/hooks
npx lefthook install

Depending on your code editor, there should be various tools that can run our linters and display the results inline based on the configurations we have specified in the Discourse project.

6) Update your branch

git fetch origin
git rebase origin/main

7) Fork

git remote add mine git@github.com:<your user name>/discourse.git

8) Push to your remote

git push mine new_discourse_branch

9) Issue a Pull Request

Before submitting a pull-request, clean up the history, go over your commits and squash together minor changes and fixes into the corresponding commits. You can squash commits with the interactive rebase command:

git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i

< the editor opens and allows you to change the commit history >
< follow the instructions on the bottom of the editor >

git push -f mine new_discourse_branch

In order to make a pull request,

  • Navigate to the Discourse repository you just pushed to (e.g. https://github.com/your-user-name/discourse)
  • Click “Pull Request”.
  • Write your branch name in the branch field (this is filled with “main” by default)
  • Click “Update Commit Range”.
  • Ensure the changesets you introduced are included in the “Commits” tab.
  • Ensure that the “Files Changed” incorporate all of your changes.
  • Fill in some details about your potential patch including a meaningful title. Be sure to follow the GitHub commit prefix convention.
  • Click “Send pull request”.

Thanks for that – we’ll get to your pull request ASAP, we love pull requests!

10) Responding to Feedback

The Discourse team may recommend adjustments to your code. Part of interacting with a healthy open-source community requires you to be open to learning new techniques and strategies; don’t get discouraged! Remember: if the Discourse team suggest changes to your code, they care enough about your work that they want to include it, and hope that you can assist by implementing those revisions on your own.

Though we ask you to clean your history and squash commit before submitting a pull-request, please do not change any commits you’ve submitted already (as other work might be build on top).

Thank you for contributing to the Discourse open source project!


Last Reviewed by @SaraDev on 2022-06-02T01:00:00Z

72 Likes