-
Notifications
You must be signed in to change notification settings - Fork 83
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: update readme, remove docker files and references (#1178)
* docs: update readme and contributing section * remove docker files * Merge branch 'master' into docsupdate * Merge branch 'master' into docsupdate * more updates to readme and contributing * Merge branch 'docsupdate' of https://github.com/ocadotechnology/rapid-router into docsupdate
- Loading branch information
Showing
4 changed files
with
83 additions
and
145 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,30 +1,30 @@ | ||
|
|
||
| # Contributing Guidelines | ||
|
|
||
| Thanks for helping out Code For life's Rapid Router! Here are a few guidelines to help your contributions to be accepted :) | ||
| Thanks for helping out Code For Life's Rapid Router! Here are a few guidelines to help your contributions to be accepted :) | ||
|
|
||
| ## Prerequisites | ||
| ## Tracking Issues | ||
|
|
||
| We use Zenhub to track our issues, you can find our workspace [here](https://app.zenhub.com/workspaces/code-for-life-team-56f2afba6e54555c586f6db3/boards?repos=18399425,49142916,22154147,39072690,96999382) | ||
| We use Zenhub to track our issues, you can find [our workspace here](https://github.com/ocadotechnology/rapid-router#workspaces/code-for-life-development-56f2afba6e54555c586f6db3/board?repos=39072690,22154147,18399425,49142916,219226351). | ||
| We recommend to add [Zenhub chrome extension](https://www.zenhub.com/extension) to integrate directly into Github's user interface. | ||
|
|
||
| ## Submitting an issue | ||
| ## Submitting a bug report or a feature request | ||
|
|
||
| If you find a bug, want to suggest feature request or improvement, please open an issue for it using one of the issue templates. | ||
| If you find a bug or want to suggest a feature request or improvement, please open an issue for it using one of the issue templates. | ||
|
|
||
| > One word of caution: please do not add any issues related to security. Evil hackers are everywhere nowadays... If you do find a security issue, let us know using our [contact form][c4l-contact-form]. | ||
| > One word of caution: please do not add any issues related to security. Evil hackers are everywhere nowadays... If you do find a security issue, let us know using our contact form [on the website][c4l] (scroll down and click `Contact us`). | ||
| ## Pull Request Guidelines | ||
|
|
||
| Once you submit a PR, we will review it via [Reviewable](https://reviewable.io/). To make the review go smoothly we recommend following the guidelines below: | ||
|
|
||
| * Include unit tests when you contribute new features, as they help to a) prove that your code works correctly, and b) guard against future breaking changes to lower the maintenance cost. | ||
| - Include unit tests when you contribute new features, as they help to a) prove that your code works correctly, and b) guard against future breaking changes to lower the maintenance cost. | ||
|
|
||
| * Bug fixes also generally require unit tests, because the presence of bugs usually indicates insufficient test coverage. | ||
| - Bug fixes also generally require unit tests, because the presence of bugs usually indicates insufficient test coverage. | ||
|
|
||
| * Use the [black formatter](https://black.readthedocs.io/en/stable/installation_and_usage.html) on your code. | ||
| - Use the [black formatter](https://black.readthedocs.io/en/stable/installation_and_usage.html) on your code. | ||
|
|
||
| * When you respond to changes based on comments from a code review, please reply with "Done." so that we get a notification. | ||
| - When you respond to changes based on comments from a code review, please reply with "Done." so that we get a notification. | ||
|
|
||
| We follow [Semantic Versioning](https://semver.org/) in this project. The version automatically gets bumped up based on the content of the PR title and description. For this we follow the [Conventional Commits Specification](https://www.conventionalcommits.org). Please make sure the PR title and description follows this specification. | ||
|
|
||
| [c4l-contact-form]: https://www.codeforlife.education/help/#contact | ||
| [c4l]: https://www.codeforlife.education/ |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,141 +1,102 @@ | ||
| # Rapid Router (codename: ocargo) | ||
|
|
||
| [](https://travis-ci.org/ocadotechnology/rapid-router) | ||
| [](https://github.com/ocadotechnology/rapid-router/actions/workflows/ci.yml) | ||
| [](https://codecov.io/gh/ocadotechnology/rapid-router) | ||
| [](https://codeclimate.com/github/ocadotechnology/rapid-router) | ||
| [](https://crowdin.com/project/code-for-life) | ||
|
|
||
| ## A [Code for Life](https://www.codeforlife.education/) project | ||
| * Rapid Router is a [Code for Life](https://www.codeforlife.education/) project, aimed at teaching primary-school children programming concepts through a vehicle routing | ||
| game. | ||
| Ocado Technology's [Code for Life initiative](https://www.codeforlife.education/) has been developed to inspire the next generation of computer scientists and to help teachers deliver the computing curriculum. | ||
| * This repository hosts the source code of the **Rapid Router game**. | ||
| * The other repos for Code For Life: | ||
| * the main portal (as well as registration, dashboards, materials...), [Code For Life Portal](https://github.com/ocadotechnology/codeforlife-portal) | ||
| * the new game for teenagers, [currently at a very early stage](https://github.com/ocadotechnology/aimmo) | ||
| * the [deployment code for Google App Engine](https://github.com/ocadotechnology/codeforlife-deploy-appengine) | ||
| ## Code for Life and Rapid Router Overview | ||
|
|
||
| ## To use the app | ||
| Go to the official [Code For Life website][c4l]. | ||
| Rapid Router is a [Code for Life][c4l] project, aimed at teaching primary school children programming concepts through a vehicle routing game. | ||
| Ocado Technology's [Code for Life][c4l] initiative has been developed to inspire the next generation of computer scientists and to help teachers deliver the computing curriculum. | ||
|
|
||
| ## To run localy with Docker | ||
| This repository hosts the source code of the **Rapid Router game**. | ||
|
|
||
| * Install Docker https://www.docker.com/ | ||
| The other repos for Code For Life: | ||
|
|
||
| * Run `docker-compose up` | ||
| - the main portal or the website: [Code For Life Portal](https://github.com/ocadotechnology/codeforlife-portal) | ||
| - our second game for older children: [Kurono (code name: aimmo)](https://github.com/ocadotechnology/aimmo) | ||
| - the [deployment code for Google App Engine](https://github.com/ocadotechnology/codeforlife-deploy-appengine) | ||
|
|
||
| * Navigate to http://localhost:8000 | ||
| ## How to play | ||
|
|
||
| ## To run the app locally | ||
| Go to [Code For Life website][c4l]. You can [play Rapid Router](https://www.codeforlife.education/rapidrouter/) right away. You can register and log in as teacher or independent student to save your progress. | ||
|
|
||
| * Clone the repo: `https://github.com/ocadotechnology/rapid-router.git`. Fork it first if you want to contribute, and work on a separate branch for your work. | ||
| ## How to set up and run locally | ||
|
|
||
| Clone the repo: `https://github.com/ocadotechnology/rapid-router.git`. | ||
|
|
||
| > If you want to contribute, [fork it first](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo), work on a branch, make a fix, and submit a pull request. | ||
| ### Ubuntu / Linux Mint | ||
| * Install prerequisites | ||
| * `sudo apt-get install git` | ||
| * `sudo apt-get install python-dev python-pip` | ||
| * `sudo pip install virtualenvwrapper` | ||
| * `sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev gettext` | ||
| * `sudo apt-get install ruby2.0` | ||
| * `sudo gem install sass -v 3.3.4` - tested to work with Ruby >1.9 and <2.3.6 | ||
|
|
||
| * Make and activate a virtualenv using [pipenv](https://pypi.org/project/pipenv/) | ||
|
|
||
| * `pip install pipenv` | ||
| * `pipenv shell` | ||
|
|
||
| ### Mac OS | ||
| * Install prerequisites | ||
| * `brew install rbenv` | ||
| * `brew install pyenv` | ||
| * `brew install pyenv-virtualenv` | ||
|
|
||
| * Update `.zshrc` with the following | ||
| * `eval "$(rbenv init -)"` | ||
| * `eval "$(pyenv init -)"` | ||
| * `eval "$(pyenv virtualenv-init -)"` | ||
|
|
||
| * Close and open terminal | ||
|
|
||
| * Run the following commands | ||
| * `rbenv install 2.2.9` | ||
| * `brew install zlib` | ||
| * `brew install readline xz` | ||
| * `xcode-select --install` | ||
| * `pyenv install 2.7.14` | ||
|
|
||
| * Finally, go to the project root and run the following commands | ||
| * `pyenv local 2.7.14` | ||
| * `rbenv local 2.2.9` | ||
|
|
||
| #### Mac OS Mojave | ||
|
|
||
| ##### Pillow | ||
| On MacOS Mojave there is an error when installing `Pillow`. | ||
| To fix this issue you need to run the following command: | ||
| ``` | ||
| sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target / | ||
| ``` | ||
| cf: https://github.com/python-pillow/Pillow/issues/3438#issuecomment-435169249 | ||
|
|
||
| ##### Pyexpat | ||
| If you have the following error: `ImportError: No module named pyexpat` when installing `pyenv 2.7.14`, then you can try using the following command: | ||
| ``` | ||
| SDKROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.14.sdk MACOSX_DEPLOYMENT_TARGET=10.14 pyenv install 2.7.14 | ||
| ``` | ||
| cf: https://github.com/pyenv/pyenv/issues/1066#issuecomment-504710495 | ||
| - Run `sudo apt-get install python-dev`. | ||
|
|
||
| - Run `sudo apt-get update` to save having to do it later in the process. | ||
|
|
||
| - Follow the instructions for [installing pyenv](https://github.com/pyenv/pyenv#installation). | ||
|
|
||
| - Run `sudo apt-get install python-pip`. | ||
|
|
||
| - Run `pip install pipenv` to get the [pipenv](https://pipenv.readthedocs.io/en/latest/) virtual environment. | ||
|
|
||
| ### Mac | ||
|
|
||
| - Get the [brew](https://brew.sh/) package manager. | ||
|
|
||
| - It's recommended to update sqlite3 as Mac default version may be incompatible. Check [common issues here](https://github.com/ocadotechnology/aimmo/blob/development/docs/common-issues.md). | ||
| To update sqlite3 with brew: `brew install sqlite3`. Then follow the instructions in `brew info sqlite3` before installing a python version with `pyenv`. | ||
|
|
||
| ##### Missing sass | ||
| If you have the following error: `pipeline.exceptions.CompilerError: env: sass: No such file or directory`, then you need to install sass: | ||
| ``` | ||
| gem install sass | ||
| If you need to have sqlite first in your PATH, run: | ||
| echo 'export PATH="/usr/local/opt/sqlite/bin:$PATH"' >> ~/.zshrc | ||
| For compilers to find sqlite you may need to set: | ||
| export LDFLAGS="-L/usr/local/opt/sqlite/lib" | ||
| export CPPFLAGS="-I/usr/local/opt/sqlite/include" | ||
| ``` | ||
|
|
||
| ### Running the Portal | ||
| * `./run` in your rapid-router directory - This will: | ||
| * install all of the dependencies using pip | ||
| * sync the database | ||
| * collect the static files | ||
| * run the server | ||
| * Once you see `Quit the server with CONTROL-C`, you can open the portal in your browser at `localhost:8000`. | ||
| - Then install pyenv with the right sqlite3 version (make sure `LDFLAGS` and `CPPFLAGS` are set as above): `brew install pyenv`. | ||
|
|
||
| - Run `brew install pipenv`. | ||
|
|
||
| ### Development and tests | ||
|
|
||
| - Run `pipenv install --dev` to get the requirements for the project. | ||
|
|
||
| - Followed by `pipenv shell` to activate the virtual env. | ||
|
|
||
| - `./run` - This will: | ||
| - sync the database | ||
| - collect the static files | ||
| - run the server | ||
| - Once you see `Quit the server with CONTROL-C`, you can open the portal in your browser at `localhost:8000`. | ||
|
|
||
| - Run `pytest` to run unit tests. All tests will be run on github when PR is submitted, but it's good to check locally too to make sure the tests run successfully after your changes. | ||
|
|
||
| ### Localisation | ||
|
|
||
| If you have problems seeing the portal on machines with different locale (e.g. Polish), check the terminal for errors mentioning `ValueError: unknown locale: UTF-8`. If you see them, you need to have environment variables `LANG` and `LC_ALL` both set to `en_US.UTF-8`. | ||
|
|
||
| - Either export them in your `.bashrc` or `.bash_profile` | ||
| - or restart the portal with command `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 ./run`. | ||
|
|
||
| * If you have problems seeing the portal on machines with different locale (e.g. Polish), check the terminal for errors mentioning `ValueError: unknown locale: UTF-8`. If you see them, you need to have environment variables `LANG` and `LC_ALL` both set to `en_US.UTF-8`. | ||
| * Either export them in your `.bashrc` or `.bash_profile` | ||
| * or restart the portal with command `LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 ./run`. | ||
| For localisation admins: | ||
|
|
||
| ## Localisation | ||
| * For localisation admins: | ||
| * `./run --with-translation-tools` in your rapid-router dir to include the translation/localisation libraries | ||
| * You will need your crowdin api key locally in the `CROWDIN_API_KEY` environment variable, e.g. `export CROWDIN_API_KEY=<key>`. This can be obtained from [the settings page](https://crowdin.com/project/code-for-life/settings#integration) | ||
| * Set your `django_language` cookie to `lol-us` to enable in-context localisation | ||
| - `./run --with-translation-tools` in your rapid-router dir to include the translation/localisation libraries | ||
| - You will need your crowdin api key locally in the `CROWDIN_API_KEY` environment variable, e.g. `export CROWDIN_API_KEY=<key>`. This can be obtained from [the settings page](https://crowdin.com/project/code-for-life/settings#integration) | ||
| - Set your `django_language` cookie to `lol-us` to enable in-context localisation | ||
|
|
||
| ## To contribute | ||
| __Guidelines__ Please read the [contributing guidelines](CONTRIBUTING.md) first, thank you.<br> | ||
| You can also read about the [life cycle of a code change](docs/life-cycle-of-a-code-change.md).<br> | ||
|
|
||
| __Found a problem? Please check whether it has already been reported in our [issue tracker][issues] first!__ If not, | ||
| [add it][add-issue]. Please make sure that you give us a suitable level of detail about the symptoms and how to | ||
| reproduce it. Please label it as a "bug". | ||
| Check our [contributing section](https://github.com/ocadotechnology/rapid-router/contribute). It contains the guidelines and issues labelled as "good first issue," selected for their relative approachability for first-time contributors. | ||
|
|
||
| One word of caution: please do not add any issues related to security. Evil hackers are everywhere nowadays... If you do find a security issue, let us know using our [contact form][c4l-contact-form]. | ||
| **Found a problem? Please check whether it has already been reported in our [issue tracker][issues] first!** If not, [add it][add-issue] as a bug report. Please make sure that you give us a suitable level of detail about the symptoms and how to reproduce it. | ||
|
|
||
| __Want to suggest a feature? Please check whether it has already been added to our [issue tracker][issues] first!__ if | ||
| not, [add it][add-issue]. Please make sure that you give us a suitable level of detail about the feature. Please label | ||
| it as a "suggestion". Please note that we may not act upon all suggestions, if they are not in line with the direction | ||
| we want to take the project, or if we don't have the development resources to get it done. | ||
| You can also [submit a feature request][add-issue]. Make sure that you give us a suitable level of detail about the feature. Please note that we may not act upon all suggestions, if they are not in line with the direction we want to take the project, or if we don't have the development resources to get it done. | ||
|
|
||
| __Want to help develop?__ You can contact us using this [contact form][c4l-contact-form] and we'll get in touch as soon as possible. To know what's going on, check out the [issue tracker][issues]. The | ||
| [issues with the 'ready for pickup' label][ready-for-pickup] are tasks we think are ready to be picked up. Once you have | ||
| chosen an issue, make sure you assign it to yourself so others don't also pick it up. Develop it on your fork of the | ||
| project. Please ensure all files have the license at the top (see another source file for an example). Once you are | ||
| happy that it works, and have written tests for it, submit a pull request. We'll then look to review the changes. If it | ||
| looks good, we'll merge it. If we find issues with it, we'll let you know and hopefully we can work with you to improve | ||
| it and get it re-submitted. If it is a change that we just don't want, we'll reject it. | ||
| > One word of caution: **please do not add any issues related to security**. Evil hackers are everywhere nowadays... If you do find a security issue, let us know using our contact form on [the website][c4l]. (Scroll down, click on `Contact us`) | ||
| [c4l]: https://www.codeforlife.education/ | ||
| [virtualenv]: https://stackoverflow.com/a/13855464 | ||
| [c4l-portal]: http://github.com/ocadotechnology/codeforlife-portal/ | ||
| [c4l-contact-form]: https://www.codeforlife.education/contact/ | ||
| [issues]: https://github.com/ocadotechnology/rapid-router/issues | ||
| [add-issue]: https://github.com/ocadotechnology/rapid-router/issues/new | ||
| [ready-for-pickup]: https://github.com/ocadotechnology/rapid-router/labels/ready%20for%20pickup | ||
| [add-issue]: https://github.com/ocadotechnology/rapid-router/issues/new/choose |
This file was deleted.
Oops, something went wrong.