Features
What it is?
The Discourse Code Review plugin provides 2 way integration with GitHub code repositories. It allows your team to review commits to a repository leveraging Discourse features and plugins such as assign, whispers, notification, custom workflows and so on. Each commit to a repository becomes a topic. Replies to the topic are mirrored on GitHub. Integration is bi-directional meaning you can comment on Discourse and see it in GitHub or comment in GitHub and see it in Discourse.
It provides a very powerful workflow for teams who need to to review all commits to any number of repositories.
It allows you to ensure that multiple team members are aware of all changes applied to repositories. You can mark commits for follow-up, assign out review work and more.
Note: When viewing a topic that can be approved, you can use the y button on your keyboard to approve commits faster.
Can I see it in Action?
Discourse maintains https://review.discourse.org/ this site is public and anyone can sign up using GitHub credentials. The site only surfaces a subset of features to non staff members. A more complete example may be:
On GitHub the same topic looks like this:
Configuration
The plugin relies on GitHub webhooks to discover repositories and changes on repositories. For a minimal configuration you will need to set the following setting to a secret string.
code review github webhook secret
Once set on your GitHub repository setup a webhook with:
Payload URL: https://YOUR_DISCOURSE/code-review/webhook
Content Type: application/json
Secret: the value of code review github webhook secret
Event Types:
- Commit comments
- Issue comments
- Pull requests
- Pull request reviews
- Pull request review comments
- Pushes
The plugin provides the following additional site settings:
code review api username : GitHub is very restrictive with the number of anonymous API requests it allows, this setting allows you to use a Discourse user’s account keys for /comments and /commit requests. This heavily reduces chances of hitting rate limits.
code review catch up commits : number of commits to “catch up” and create topics for when you encounter a new repo.
code review default parent category: choose a default parent category for categories created by the plugin
code review pending tag: Tag to apply to all unreviewed commits, pending by default
code review approved tag: Tag to apply to approved commits, approved by default
code_review_followup_tag: Tag to apply to follow-up commits follow-up by default
code review allow self approval: Are staff allowed to approve own commits?
code review default mute new categories: New categories created by code review are muted for users by default
code review skip duration minutes: Clicking the skip button on a commit will prevent that commit from showing up again for the number of minutes set by this setting.
CHANGELOG
TODO
Extras
How Discourse Uses This Plugin
TL;DR - This plugin was designed to complement the Discourse team’s use of GitHub for code review.
More Information
From @sam:
-
We still use PRs using GitHub UI and love doing PRs for lots of changes. Nothing has changed here. GitHub is fantastic, we love GitHub. They have an excellent workflow for changes that have not yet landed. However…
-
GitHubs workflow for changes that have been committed directly to the repository is terrible.
-
Review fills a gap that simply can not be filled with GitHub today, we would like at least one team member to review every change made to our various Discourse owned git repos. If we are to use the GitHub provided UI nobody will ever be allowed to do anything but pull requests. This would slow us down enormously.
-
We need the ability to communicate privately without the whole world knowing with regards to certain changes. For example: We better get this awesome fix deployed to <insert giant company name> ASAP, @sam can you take care of it ?
-
We need the ability to approve changes made or request follow-up, this is not something the GitHub UI offers.
-
We need the ability to assign particular commits to a user. Say @sam makes a commit containing some mistakes It is nice that we can directly assign him that particular commit, mark it for followup and then keep track of it being followed up.
-
Discourse is pretty fantastic at this whole conversation thing, and the little features make a pretty big difference, I can see when people are typing. I never need to refresh pages for changes to pop up. Quoting is really nice, image uploads are nice, and so on.
-
Discourse is really good at read state, you get very strong guarantees that you read every single thing once, with GitHub I have no idea what commits I read and which I did not. We have an incredibly efficient to cope with firehose of information.
And the list goes on…
So review acts as a complement to GitHub, we use GitHub at the moment to cope with changes that have not yet landed. And we use review to properly handle changes that have already landed.
