Discourse Code Review

official

(Sam Saffron) #1

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.

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:

Installation

To install the plugin add: https://github.com/discourse/discourse-code-review.git to your app.yml.

GitHub repo: https://github.com/discourse/discourse-code-review

Review cateory: https://review.discourse.org/c/discourse-code-review

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

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 users 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 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?

Feedback

This plugin is being actively developed, we started gathering some feedback at: site feedback - Discourse Reviews


(Dan Fabulich) #2

Can you say another few words about the advantages (and disadvantages, if any) of doing Github code reviews in Discourse? Why not use Github’s UI? (Why pay for Github if you’re not planning to use its UI?)


#3

Does this also support discussing over pull requests? I feel that would also help a lot for example when there’s a one-man-band doing the dev, but he’s also accepting PRs.


(Sam Saffron) #4

I have a 1000 word blog post in my mind about it, but I can do a quick bullet point for now.

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

It is all early days but this has transformed the way I work and taught me so much. @TheBestPessimist PR support will probably happen one day, but for now the big focus is around complementing the weak parts of our existing GitHub workflow. PRs are working really well for us.


(Cosmin Popescu) #5

Hello !

Congrats for idea :smiley:

It is possible to integrate this plugin with Bitbucket or Gitlab ?
Or private repos ?

Thank you !