Contributing to Discourse development

Documentation Contributing
1

:bookmark: This guide is designed for those who wish to contribute to the Discourse open-source project, detailing the setup and conventions necessary for effective collaboration.

:person_raising_hand: Required user level: While anyone can contribute code, you will need to be familiar with Ruby and JavaScript.

Summary

This documentation will cover the following:

  • Setting up your development environment
  • Understanding where to begin contributing
  • Creating and working with Discourse plugins
  • Contributing to the Discourse core
  • Coding conventions to follow
  • Submitting your contributions on GitHub

Setting up the development environment

Before you start contributing, ensure your development environment is properly set up. Follow the appropriate guide for your platform:

Knowing where to begin

Discourse is a large project, and understanding its underlying technologies such as Ruby and JavaScript is essential. For guidance on how to start, refer to the newbie guide.

Creating and working with plugins

Plugins offer a way to understand Discourse internals in manageable portions and allow you to start contributing code easily. Begin with:

For inspiration, explore popular ideas in feature and extras.

Contributing to Discourse core

Discourse core code is managed in the core repository on GitHub.

Signing the CLA

Before contributing, read and sign the Electronic Discourse Forums Contribution License Agreement. The team cannot legally accept pull requests (PRs) from users who haven’t signed the CLA.

Warming up with starter tasks

Explore the pr-welcome tag for good tasks to begin.

Work through the bugs list

Fix bugs from the list of open bugs ordered by likes. Leave a note if you’re working on a bug - if you don’t complete it, leave any relevant notes for someone else to continue your work.

Help with feature topics

Contribute details and mockups to feature requests to aid their approval process. Remember, not every feature will be included in core.

Improve performance

We welcome pull requests that enhance the client or server-side performance, focusing on high-impact areas like the initial load of the front page or topic view.

Improve Discourse maintained projects

Contribute to other open-source projects maintained by Discourse. Some notable projects include:

Coding conventions

Naming is CRITICAL

Aim for 100% parity between terms used on the site and names of classes and columns in the database (e.g., “posts”).

Compatibility with the latest versions of dependencies is CRITICAL

Ensure compatibility with the latest stable releases of libraries like Rails, Ruby, and Ember. Test for regressions when updating dependencies.

Test-only contributions are welcome

Test contributions are welcomed, especially for untested processes and controller actions. Avoid mocking unless absolutely necessary.

Refactor-only contributions are NOT welcome

Avoid submitting refactor-only pull requests. Instead, fix a bug or implement a feature while improving the code.

Submitting code on GitHub

Step-by-step workflow

  1. Clone the Discourse repository:

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

  2. Create a new branch:

    cd discourse
git checkout -b new_discourse_branch

  3. Code:

    • Adhere to existing code conventions you find in the code.
    • Include tests and ensure they pass.
    • Reference relevant discussions on the Discourse meta forum.

  4. Follow 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

  5. Commit:

    git commit -m "A short summary of the change" -m "A detailed description of the change"

    Never leave a commit message blank - this is a helpful guide for writing commit messages. The message should start with a short (max 72 characters) summary in the first line, followed by a blank line, and then a more detailed description of the change. You can use markdown syntax for simple styling if needed.

    Make sure to prefix commit titles according to the Discourse conventions.

    5 (a). Linting:
    JavaScript code is linted with eslint and formatting conditions of prettier. Ruby is linted 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. Run this in your project root:
      mkdir .git/hooks
npx lefthook install

  6. Update your branch:

    git fetch origin
git rebase origin/main

  7. Fork:

    git remote add mine git@github.com:<your-username>/discourse.git

  8. Push to your remote:

    git push mine new_discourse_branch

  9. Issue a pull request:

    • Navigate to your repository on GitHub.
    • Click “Pull Request”.
    • Write your branch name in the branch field.
    • Click “Update Commit Range”.
    • Verify changes in “Commits” and “Files Changed” tabs.
    • Provide a title and description.
    • Click “Send 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
  1. Respond to feedback:
    • Be responsive to feedback and ready to implement suggested changes.
    • Remember, feedback means your work is valued and intended for inclusion.

Thank you for contributing to the Discourse open-source project!

Last edited by @hugh 2024-06-20T01:45:54Z

Last checked by @hugh 2024-06-20T01:46:07Z

Check documentPerform check on document:
73 Likes
112

Was this removed on purpose?

This doesn’t work anymore

2 Likes
114

Thanks @Moin - I have remedied this in the topic!

3 Likes