A collaborative writing platform built on top of GitHub, originally designed for open policymaking and manifesto writing.
It has two main functions:
Provide a user-friendly interface to make changes (using pull requests) to GitHub-hosted Jekyll websites, using Markdown.
Monitor discussion in those pull requests, and layer on a voting system to determine what should be merged in. Voting is done using special symbols in pull requests, which are counted by the app. Status is set using the GitHub commit status API.
The system was originally implemented for the collaborative manifesto project at https://openpolitics.org.uk/manifesto. The canonical instance of this app for that project is https://votebot.openpolitics.org.uk
... to be written ...
... to be written ...
If you want to run your own open democratic platform, you can! This isn't a simple process yet, but we'll help you through as best we can...
Note that the style and headers of the deployed app will still match the OpenPolitics Manifesto version. A change for that will be coming soon.
You can use Groupthink to edit any GitHub repository you like, but we've set up a template site using GitHub Pages and Jekyll to get you started.
Click here to create your very own copy, ready to go.
Then visit the cloned repository's settings page, and:
template
master
branchYour new site will be visible at https://{{your-username}}.github.io/{{repository-name}}
. If you've set up a CNAME on your user site, the URL will be different, but you're advanced enough to work that out yourself.
Visit the Personal Access Tokens page on your GitHub account to create a token for accessing the API.
Note: you may want to create a new 'robot' GitHub account for this token. For example, the OpenPolitics Manifesto uses openpolitics-bot.
Generate a new token. You'll need to allow the following permissions:
Keep hold of the generated token - you'll need it in a minute.
Visit the Developer applications page on your GitHub account to set up user login via GitHub. Register a new application; in the homepage and callback URLs enter the URL of the application you are about to deploy. Yes, that's slightly tricky. It will be something like https://your-unique-groupthink-app-name.onrender.com
. Make up the your-unique-groupthink-app-name
part. The name of your project will probably do.
Again, keep hold of the client ID and secret. You'll need them in the next step.
Note: if you created the manifesto repository in a GitHub organisation, the OAuth application should be owned by the same organisation. If not, users in the organisation will not be able to create new proposals unless they manually grant access to the organisation when they log in.
Hit this big deploy button here:
Then, enter all the relevant details. Use the same app name you did in the step above, your-unique-groupthink-app-name
. If it's taken, don't worry, you can go back and edit the GitHub application settings later.
Enter the personal access token, client ID, and secret from the previous stage. Enter the repository path of your cloned template site - it should be something like your-username/repository-name
.
Go to the _config.yml
file in your site's GitHub repository, and add the URL of your deployed Heroku app to the groupthink_url
setting. It will be the same as what you put in above for the GitHub application homepage, i.e. https://your-unique-groupthink-app-name.onrender.com
Visit the Heroku dashboard for your app, and on the "Resources" tab, choose the Heroku Scheduler. Add a new job, rake nightly
, on a free dyno on a daily schedule. It's probably sensible to run it sometime in the small hours of the morning.
This task will run the following tasks, in this order:
rake merge
: merges any proposals that have been passedrake close
: closes any proposals that are over the maximum agerake update
: reloads data from github, counts votes, and performs time checks.Because update
is run last, proposals will be marked as passed or dead, and closed or merged on the next run of the rake task. If run nightly, this gives 24 hours of grace before automatic actions are taken.
If you want to keep your version of groupthink up to date with the latest changes, visit the Heroku dashboard for your app, and enable automatic deployment on the Deploy tab.