diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 7c48e10..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,62 +0,0 @@ -Contributing -============ - -All kinds of contributions to Gavel are greatly appreciated. For someone -unfamiliar with the code base, the most efficient way to contribute is usually -to submit a [feature request](#feature-requests) or [bug report](#bug-reports). - -If you want to dive into the source code, you can submit a [patch](#patches) as -well. Working on [existing issues][issues] is super helpful! - -Feature Requests ----------------- - -Do you have an idea for an awesome new feature for Gavel? Please [submit a -feature request][issue]. It's great to hear about new ideas. - -If you are inclined to do so, you're welcome to [fork][fork] Gavel, work on -implementing the feature yourself, and submit a patch. In this case, it's -*highly recommended* that you first [open an issue][issue] describing your -enhancement to get early feedback on the new feature that you are implementing. -This will help avoid wasted efforts and ensure that your work is incorporated -into the code base. - -Bug Reports ------------ - -Did something go wrong with Gavel? Sorry about that! Bug reports are greatly -appreciated! - -When you [submit a bug report][issue], please include relevant information such -as Gavel version, operating system, configuration, error messages, and steps to -reproduce the bug. The more details you can include, the easier it is to find -and fix the bug. - -Patches -------- - -Want to hack on Gavel? Awesome! - -If there are [open issues][issues], you're more than welcome to work on those - -this is probably the best way to contribute to Gavel. If you have your own -ideas, that's great too! In that case, before working on substantial changes to -the code base, it is *highly recommended* that you first [open an issue][issue] -describing what you intend to work on. - -**Patches are generally submitted as pull requests.** Patches are also -[accepted over email][email]. - -Any changes to the code base should follow the style and coding conventions -used in the rest of the project. The version history should be clean, and -commit messages should be descriptive and [properly -formatted][commit-messages]. - ---- - -If you have any questions about anything, feel free to [ask][email]! - -[issue]: https://github.com/anishathalye/gavel/issues/new -[issues]: https://github.com/anishathalye/gavel/issues -[fork]: https://github.com/anishathalye/gavel/fork -[email]: mailto:me@anishathalye.com -[commit-messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index 38ef442..0000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,117 +0,0 @@ -# Development - -Development happens in the `develop` branch, while the latest stable version is -in the `master` branch. - -## Setup - -The easiest way to get started on hacking on Gavel is to use [Vagrant][vagrant] -and run everything inside a virtual machine. - -If you really want, you could also manually install stuff on your machine and -get Gavel running there. - -Also, if you need help with anything, feel free to ask in the [Gitter -chat][gitter]. - -### Vagrant - -Make sure you have [Vagrant][vagrant] installed on your machine. - -To start the VM: - -```bash -vagrant up -``` - -If you need to power off the VM at any point, run: - -```bash -vagrant halt -``` - -To ssh into the VM: - -```bash -vagrant ssh -``` - -**Note: the rest of the commands in this section are meant to be run _inside -the VM_, not on the host machine.** - -The project directory gets synchronized to `/gavel` inside the VM. Once you're -SSHed into the box, install Gavel's dependencies. You should only need to do -this once, unless Gavel's dependencies change: - -```bash -cd /gavel -virtualenv env -source ./env/bin/activate -pip install -r requirements.txt -``` - -Next, set up Gavel. You should only need to do this once, unless Gavel's config -options change or Gavel's database schema changes: - -```bash -cp config.vagrant.yaml config.yaml # set good defaults -python initialize.py -``` - -Finally, you're ready to run Gavel: - -```bash -DEBUG=true python runserver.py -``` - -Now, on your local machine, you should be able to navigate to -`http://localhost:5000/` and see Gavel running! You should be able to go to -`http://localhost:5000/admin` and login with the username "admin" with the -password "admin". - -If you'd like to enable sending emails, you'll also need to run a celery worker -with: - -```bash -celery -A gavel:celery worker -``` - -**While developing, you should keep `vagrant rsync-auto` running on the host -machine so that whenever you change any files, they're automatically synced -over to the VM.** When the app running in the VM detects changed files, it'll -automatically restart (because of the debug flag). - -### Manual setup - -This is not the recommended way to do things, so this section isn't super -detailed. - -* Be using Python 3 -* Install Postgres -* Do development inside a [virtualenv][virtualenv] -* `pip install -r requirements.txt` -* `cp config.template.yaml config.yaml` -* Edit config file for your setup -* `python initialize.py` -* `DEBUG=true python gavel.py` - -## Tips - -* While developing, it's helpful to set the environment variable `DEBUG=true` - -* If Gavel's database schema is changed or if the database gets messed up in - any way, you can reset everything by running (in the Vagrant VM): - - ```bash - sudo su postgres -c "dropdb gavel && createdb gavel" - python initialize.py - ``` - -* This project uses [EditorConfig][editorconfig]. - [Download][editorconfig-download] a plugin for your editor! - -[gitter]: https://gitter.im/anishathalye/gavel -[vagrant]: https://www.vagrantup.com/ -[virtualenv]: https://virtualenv.pypa.io/en/stable/ -[editorconfig]: http://editorconfig.org/ -[editorconfig-download]: http://editorconfig.org/#download diff --git a/README.md b/README.md index 5c77bbe..2366e03 100644 --- a/README.md +++ b/README.md @@ -1,182 +1,5 @@ -Gavel banner +Gavel banner -**Gavel** is a project expo judging system. +**Gavel** is a project expo judging system. Documentation can be found at the link below. -Gavel was originally built for HackMIT and first used at HackMIT 2015. It has -been used by [dozens][users] of other events since then. - -**If you use Gavel for your event, please add yourself to [this list][users]! -It only takes a minute, and knowing that Gavel is helping real events helps -keep us going <3** - -[![Join the chat at https://gitter.im/anishathalye/gavel](https://badges.gitter.im/anishathalye/gavel.svg)](https://gitter.im/anishathalye/gavel?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - -## Demo - -

- - Gavel screenshot - -

- -See the demo video -[here](http://www.anishathalye.com/2016/09/19/gavel-an-expo-judging-system/)! - -## Users - -See [here][users] for a list of events that have used Gavel in the past. - -**If you use Gavel for your event, please add yourself to the list! It only -takes a minute, and knowing that Gavel is helping real events helps keep us -going <3** - -and adding yourself to the list helps keep me motivated to continue -working on the software :) - -## Design - -Gavel is based on the method of pairwise comparisons. Before you use Gavel, -it's *highly recommended* that you read about the philosophy behind the -implementation as well as hints on how to use it in practice. Read [this blog -post][blog-1] first, and then read [this blog post][blog-2]. - -## Status - -Gavel is stable software. We've used it successfully at HackMIT, and a bunch of -other hackathons and events have used it too. - -Gavel is a pretty different way of doing judging. If you want to use this for -your hackathon or event, we highly recommend that you: - -* Deploy it and play around with it ahead of time to get a feel for how the - system works -* Read the blog posts linked above to get an idea of how to structure the - judging process - -If you have any questions, feel free to [email me][email]. - -If you're able to contribute to making Gavel better, that would be **awesome**! -We'd really appreciate any kind of input, especially pull requests. - -## Deployment - -[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/weareasterisk/gavel/tree/master) - -The latest stable version is the `master` branch (and it's signed and tagged). -Development happens in the `develop` branch. - -The web application is written in **Python 3** using Flask. It also uses NumPy -and SciPy for math stuff. Doing a `pip --no-cache-dir install -r requirements.txt` should -install all the dependencies. - -The application uses Postgres for the database, so you need to have that on -your server. You need to create a database, which you can do with `createdb -gavel` (unless you're using a different database name). Before you use the app, -you need to initialize the database by running `python initialize.py`. **Note -that Gavel does not preserve database schema compatibility between versions.** - -In order to send emails, you'll need to install Redis. - -When testing, you can run the app with `python runserver.py`. In production, -you should use something like [Gunicorn][gunicorn] to serve this. You can run -the app with `gunicorn -b : -w gavel:app`. - -For sending emails, you'll also need to start a celery worker with `celery -A -gavel:celery worker`. - -## Configuration - -Before starting the app, copy `config.template.yaml` to `config.yaml` and set -all the required settings (the ones that don't have default values). - -Most settings can either be set in `config.yaml` or set as environment -variables. There's more detailed documentation in `config.template.yaml`. - -If you don't want to use the config file and use only environment variables, -set the environment variable `IGNORE_CONFIG_FILE=true`. - -## Troubleshooting - -See the [troubleshooting -guide](https://github.com/anishathalye/gavel/wiki/Troubleshooting) in the Gavel -wiki. - -## Use - -To set up the system, use the admin interface on `/admin`. Log in with the -username `admin` and the password you set. Once you're logged in, you can input -information for all the projects and judges. - -As you add judges, they'll automatically get emails with invitation links. -After that, the judging and ranking process is fully automated - the judge will -be able to read the welcome text, and then they'll be able to start judging. - -The admin panel will rank projects in real time, ordered by their inferred -quality (Mu). - -### Admin Panel Features - -* If you want to (temporarily) close the judging system, click the "Close" - button under "Global Settings" -* If you need to force re-send the invite email, use the "Email" button for the - judge in the admin panel -* If you need to manually give a judge a login link, direct them to - `/login/` -* If you want to send the next available judge to a certain project, use the - "Prioritize" button -* If you need to deactivate projects or judges at any point, use the "Disable" - button -* If a project hasn't been judged yet, you can delete it using the "Delete" - button -* If a judge hasn't started yet, you can delete them using the "Delete" button -* If you need to see details for a project or judge, click on the item ID in - the admin panel - * If you need to edit a project (name, location, or description), you can - do so on the item detail page -* If you want to sort the items in the admin panel, click on the table headers - -## Development - -Interested in hacking on Gavel? Awesome. See [DEVELOPMENT.md][development] for -a dev setup guide. - -## Notes - -If you do end up using this for your competition or hackathon, I would love to -hear about how it goes. - -If anyone has questions, feel free to email Anish (me@anishathalye.com). - -## Contributing - -Do you have a feature request, bug report, or patch? Great! See -[CONTRIBUTING.md][contributing] for information on what you can do about that. - -## Citation - -If you use Gavel in any way in academic work, please cite the following: - -``` -@misc{athalye2016gavel, - author = {Anish Athalye}, - title = {Gavel}, - year = {2016}, - howpublished = {\url{https://github.com/anishathalye/gavel}}, - note = {commit xxxxxxx} -} -``` - -## License - -Copyright (c) 2015-2018 Anish Athalye. Released under AGPLv3. See -[LICENSE.txt][license] for details. - -[blog-1]: http://www.anishathalye.com/2015/03/07/designing-a-better-judging-system/ -[blog-2]: http://www.anishathalye.com/2015/11/09/implementing-a-scalable-judging-system/ -[issues]: https://github.com/anishathalye/gavel/issues -[contributing]: CONTRIBUTING.md -[license]: LICENSE.txt -[development]: DEVELOPMENT.md -[email]: mailto:me@anishathalye.com -[gunicorn]: http://gunicorn.org/ -[users]: https://github.com/anishathalye/gavel/wiki/Users +# [Gavel Documentation](https://gavel.weareasterisk.com/) \ No newline at end of file