README.md 6.05 KB
Newer Older
1
[![coverage report](https://gitlab.kwant-project.org/zesje/zesje/badges/master/coverage.svg)](https://gitlab.kwant-project.org/zesje/zesje/commits/master)
Ruben Young On's avatar
Ruben Young On committed
2

3 4 5 6 7 8 9
# Welcome to Zesje

Zesje is an online grading system for written exams.

## Development

### Setting up a development environment
10 11 12
We recommend using the Conda tool for managing your development
environment. If you already have Anaconda or Miniconda installed,
you may skip this step.
13

14 15 16 17 18 19 20
Install Miniconda by following the instructions on this page:

https://conda.io/miniconda.html

Create a Conda environment that you will use for installing all
of zesje's dependencies:

21
    conda create -c conda-forge -n zesje-dev python=3.6 yarn
22 23 24 25 26 27 28 29 30

Then, *activate* the conda environment:

    conda activate zesje-dev

You should see `(zesje-dev)` inserted into your shell prompt.
This tells you that the environment is activated.

Install all of the Javascript dependencies:
31

32
    yarn install
33

34
Install all of the Python dependencies:
35

Jamy Mahabier's avatar
Jamy Mahabier committed
36
    pip install -r requirements.txt -r requirements-dev.txt
37

38 39 40 41
Unfortunately there is also another dependency that must be installed
manually for now (we are working to bring this dependency into the
Conda ecosystem). You can install this dependency in the following way
on different platforms:
42

Jamy Mahabier's avatar
Jamy Mahabier committed
43 44 45 46 47 48 49 50
| OS            | Command                      |
|---------------|------------------------------|
| macOS         | `brew install libdmtx`       |
| Debian/Ubuntu | `sudo apt install libdmtx0a` |
| Arch          | `pacman -S libdmtx`          |
| Fedora        | `dnf install libdmtx`        |
| openSUSE      | `zypper install libdmtx0`    |
| Windows       | *not necessary*              |
51

52 53


Jamy Mahabier's avatar
Jamy Mahabier committed
54
### Running a development server
55
Activate your zesje development environment and run
Jamy Mahabier's avatar
Jamy Mahabier committed
56 57 58 59 60 61 62 63 64

    yarn dev

to start the development server, which you can access on http://127.0.0.1:8881.
It will automatically reload whenever you change any source files in `client/`
or `zesje/`.

### Running the tests

Thomas Roos's avatar
Thomas Roos committed
65 66 67
You can run the tests by running

    yarn test
68 69 70
    
#### Viewing test coverage

71
As a test coverage tool for Python tests, `pytest-cov` is used.
72

Ruben Young On's avatar
Ruben Young On committed
73 74
To view test coverage, run

75
    yarn test:py:cov
Ruben Young On's avatar
Ruben Young On committed
76

77 78
A coverage report is now generated in the terminal, as an XML file, and in HTML format.
The HTML file shows an overview of untested code in red.
Thomas Roos's avatar
Thomas Roos committed
79

Ruben Young On's avatar
Ruben Young On committed
80
##### Viewing coverage in Visual Studio Code
RABijl's avatar
RABijl committed
81 82 83 84 85

There is a plugin called Coverage Gutter that will highlight which lines of code are covered.
Simply install Coverage Gutter, after which a watch button appears in the colored box at the bottom of your IDE.
When you click watch, green and red lines appear next to the line numbers indicating if the code is covered.

86
Coverage Gutter uses the XML which is produced by `yarn test:py:cov`, called `cov.xml`. This file should be located in the main folder.
87

Ruben Young On's avatar
Ruben Young On committed
88
##### Viewing coverage in PyCharm
89
To view test coverage in PyCharm, run `yarn test:py:cov` to generate the coverage report XML file `cov.xml` if it is not present already.
Ruben Young On's avatar
Ruben Young On committed
90 91 92 93 94

Next, open up PyCharm and in the top bar go to **Run -> Show Code Coverage Data** (Ctrl + Alt + F6).

Press **+** and add the file `cov.xml` that is in the main project directory.
A code coverage report should now appear in the side bar on the right.
RABijl's avatar
RABijl committed
95

96 97 98 99 100 101 102
#### Policy errors

If you encounter PolicyErrors related to ImageMagick in any of the previous steps, please
try the instructions listed
[here](https://alexvanderbist.com/posts/2018/fixing-imagick-error-unauthorized) as
a first resort.

103 104 105 106 107 108 109 110 111 112 113 114
### Database modifications

Zesje uses Flask-Migrate and Alembic for database versioning and migration. Flask-Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic. 

To change something in the database schema, simply add this change to `zesje/database.py`. After that run the following command to prepare a new migration:

    yarn prepare-migration

This uses Flask-Migrate to make a new migration script in `migrations/versions` which needs to be reviewed and edited. Please suffix the name of this file with something distinctive and add a short description at the top of the file. To apply the database migration run:

    yarn migrate:dev # (for the development database)
    yarn migrate # (for the production database)
115

Thomas Roos's avatar
Thomas Roos committed
116 117
### Building and running the production version

Jamy Mahabier's avatar
Jamy Mahabier committed
118 119 120 121

### Code style

#### Python
122
Adhere to [PEP8](https://www.python.org/dev/peps/pep-0008/), but use a column width of 120 characters (instead of 79).
123

Jamy Mahabier's avatar
Jamy Mahabier committed
124 125 126 127 128 129
If you followed the instructions above, the linter `flake8` is installed in your virtual environment. If you use Visual Studio Code, install the [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) extension and add the following lines to your workspace settings:

    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "[python]": {
        "editor.rulers": [120]
130
    },
Jamy Mahabier's avatar
Jamy Mahabier committed
131 132 133 134 135 136

If you use Atom, install the [linter-flake8](https://atom.io/packages/linter-flake8) plugin and add the following lines to your config:

    ".source.python":
      "editor":
        "preferredLineLength": 120
137

138 139 140 141 142 143 144
#### Javascript
Adhere to [StandardJS](https://standardjs.com/).

If you use Visual Studio Code, install the [vscode-standardjs](https://marketplace.visualstudio.com/items?itemName=chenxsan.vscode-standardjs) plugin.

If you use Atom, install the [linter-js-standard-engine](https://atom.io/packages/linter-js-standard-engine) plugin.

145 146 147
### Adding dependencies

#### Server-side
Thomas Roos's avatar
Thomas Roos committed
148 149 150 151 152
If you start using a new Python library, be sure to add it to `requirements.txt`. Python libraries for the testing are in `requirements-dev.txt`.
The packages can be installed and updated in your environment by `pip` using

    pip install -r requirements.txt -r requirements-dev.txt

153

Thomas Roos's avatar
Thomas Roos committed
154 155 156 157
#### Client-side
Yarn keeps track of all the client-side dependancies in `package.json` when you install new packages with `yarn add [packageName]`. Yarn will install and update your packages if your run

    yarn install
Thomas Roos's avatar
Thomas Roos committed
158 159

## License
160
Zesje is licensed under AGPLv3, which can be found in `LICENSE`. An summary of this license with it's permissions, conditions and limitations can be found [here](https://choosealicense.com/licenses/agpl-3.0/).