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.
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:
- All platforms: Install Discourse for Development using Docker
- Mac OS X: Beginnerâs Guide to Install Discourse on macOS for Development
- Linux (Ubuntu): Beginnerâs Guide to Install Discourse on Ubuntu for Development
- Windows: Beginnerâs Guide to Install Discourse on Windows 10 for Development
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:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- Plugin outlet locations theme component
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:
- Logster - web GUI log viewer
- Message Bus - engine for live site interactions
- Rack Mini Profiler - diagnostics tool
- Onebox - Ruby gem for URL previews
- Discourse API - API consumer
- Discourse Docker - Discourse distribution engine
- WP Discourse - WordPress plugin
- Memory Profiler - profiler for Ruby
- Ember Performance - Ember performance test suite
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
-
Clone the Discourse repository:
git clone https://github.com/discourse/discourse.git
-
Create a new branch:
cd discourse git checkout -b new_discourse_branch
-
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.
-
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
overdef self.method
for class methods - prefer
{ ... }
overdo ... end
for single-line blocks, avoid using{ ... }
for multi-line blocks - avoid
return
when not required
-
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
- It is strongly recommended that you install our pre-commit git hooks using
-
Update your branch:
git fetch origin git rebase origin/main
-
Fork:
git remote add mine git@github.com:<your-username>/discourse.git
-
Push to your remote:
git push mine new_discourse_branch
-
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
-
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 document
Perform check on document: