Discourse Development Contribution Guidelines


(Sam Saffron) #1

Environment

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

Discourse as Your First Rails App is a great starting point:
http://blog.discourse.org/2013/04/discourse-as-your-first-rails-app/

If you require further assistance, you can check out one of these guides:

All Platforms

Mac OS X

Linux (Ubuntu)

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.

Need some ideas on what to build? Just have a look through the popular ideas in /c/feature, /c/extensibility 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.

You might also want to read “What is a CLA and why do I care?”.

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 (which is also linked from the front page).

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.

Look at #RFC for larger projects

The #rfc contains “team approved” specifications for features. Feel free to work on any of them. You will also find relevant topics in the #pr-welcome tag.

If you are going to work on one of these, leave a post on the topic mentioning it.

Help convert “Feature” topics to specs

There are many open feature requests that need proper specification and team approval to be added to the product. feature - Discourse Meta feel free to participate on these topics and even create a “spec” which the team can ratify and recategorize into the spec category.

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. Read more here:

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 checkin 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.

6) Update your branch

git fetch origin
git rebase origin/master

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/master
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 “master” 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 checkin 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!


Where does Discourse stand on minor refactoring PRs
Discourse as Your First Rails App
I don't like having to use Gravatar
Keyboard shortcuts?
How does Discourse efficiently generate the topic list page? (The "Latest" page)
Bootstrap fails when plugin file specifies gem version range
[API] Creating a topic with a new tag without tag-creation permission fails silently
HTML/RTF pasting
How should short links be supported in Discourse
Here's my Categories as Sub-Reddit / Sub-Discourse Idea
Setting timeout times for oneboxes
Include performance improvements in release notes?
Clicking the pin icon works only once
Switching from erb to slim
Contributing to Discourse
Looking for resource on EmberJS integration with Rails
How to make bug reports for Discourse
Request for splitting js.topic.reply.title
Plugin Outlet Locations
Hashtag linking to categories doesn’t always work
What languages / frameworks do I need to contribute to Discourse on GitHub?
Discourse Voting
Topic List Previews
How to contribute to Discourse
Any performance-related areas you'd like investigated?
Issue regarding Docker development image
Project ideas for Google Summer of Code 2017
Installing Plugins in Discourse Development Install
Discourse Spoiler Alert
(Sam Saffron) #96

I updated the guidelines and wikified. Please keep general discussion and clarification in the “dev” category. All replies to this topic will eventually get deleted.


(Robert Rudman) #99

Out of curiosity, why is mocking heavily discouraged?


(Sam Saffron) #100

Over the years we have had a huge amount of very hard to debug and fragile tests that used mocking.

In particular mocking encourages

Test this method is implemented exactly as I initially implemented it

Overuse of mocking leads to tests that:

Test I called goto 3 times, then wrote a for loop that did 4 things

vs

Test that this API functions correctly