Update README.md on linters
[tools/hiccup/hiccup-server.git] / README.md
1 # Hiccup Server
2
3 Hiccup is intended to help Fairphone to assess the stability of the Fairphones in the field.
4 The Server side consists of two django projects: crashreports and crashreports_stats.  The former
5 implements the API endpoints for collecting crash reports, while the later implements the
6 front-end and some endpoints to access statics.
7
8 ## Setup
9
10 Python 3.6 is the only supported python version for the server code. Use this
11 version for development. It is the default version in Ubuntu 18.04, if you
12 run another OS, it is still possible to get python 3.6 (see for example
13 https://askubuntu.com/a/865569).
14
15 Make sure you have installed `python3`, `virtualenv` and `libffi-dev`.
16
17     $ sudo apt install python3 virtualenv libffi-dev
18
19 Clone Hiccup server and install it locally:
20
21     $ git clone ssh://$USER@review.fairphone.software:29418/tools/hiccup/hiccup-server
22     $ cd hiccup-server
23     $ virtualenv -p python3.6 .venv/hiccupenv
24     $ source .venv/hiccupenv/bin/activate
25     (hiccupenv) $ pip install -e .
26
27 When using a virtualenv with pyenv (e.g. to get python3.6 on Ubuntu 16.04),
28 the python executable needs to be explicitly named to make tox work (see
29 https://github.com/pyenv/pyenv-virtualenv/issues/202#issuecomment-284728205).
30
31     pyenv virtualenv -p python3.6 <installed-python-version> hiccupenv
32
33 i.e., because I have compiled python 3.6.6:
34
35     pyenv virtualenv -p python3.6 3.6.6 hiccupenv
36
37 #### Setting up PostgreSQL Server
38
39 The Hiccup server relies on a PostgreSQL database.
40
41 To set up a database server, you can install the following package:
42
43     (hiccupenv) $ sudo apt install postgresql
44
45 Then create a user and database:
46
47     (hiccupenv) $ sudo service postgresql start
48     (hiccupenv) $ sudo -u postgres createuser $USER --createdb
49     (hiccupenv) $ sudo -u postgres createdb -O $USER $USER
50
51 The settings for accessing the PostgreSQL server can be found in
52 `hiccup/settings.py` (see the `DATABASES` setting). When both the postgresql
53 server and the Hiccup server are running on the same machine and you are
54 using the same user that you used for creating the database for running the
55 server, the default settings should be fine. For all other cases a
56 `local_settings.py` file can be created in the project root directory to
57 overwrite the default settings.
58
59 Test that the configuration is correct:
60
61     (hiccupenv) $ python manage.py test
62
63 See the end of the next section to add a super-user.
64
65
66 ### Run Hiccup server
67
68 The first time you run the server, the database will be empty and the model migrations have yet to
69 happen:
70
71     (hiccupenv) $ python manage.py migrate
72
73 Then, at any later point, start the local server:
74
75     (hiccupenv) $ python manage.py runserver
76     ...
77     Starting development server at http://127.0.0.1:8000/
78     ...
79
80 The API is available at `localhost:8000/hiccup/` and the web-front-end at
81 `localhost:8000/hiccup_stats/`.
82
83 The Django admin web-front-end is at `localhost:8000/hiccup/admin`.
84
85 If you plan to browse through the Django admin web-front-end (`localhost:8000/hiccup/admin`), you
86 will need a super-user (admin) account:
87
88     (hiccupenv) $ python manage.py createsuperuser
89     ...
90     Superuser created successfully.
91
92 To browse  through the Hiccup front-end (`localhost:8000/hiccup_stats/`), the account you will
93 identify with should belong to the group `FairphoneSoftwareTeam`.
94
95 Run the following command or perform the manual steps below:
96
97     python manage.py shell -c "
98         from django.contrib.auth.models import Group, User
99         admin = User.objects.get(username='admin')
100         stats_group = Group.objects.get(name='FairphoneSoftwareTeam')
101         stats_group.user_set.add(admin)
102         "
103
104 * You need a running server and a super-user account;
105 * Go to the user list at `http://localhost:8000/hiccup/admin/auth/user/` and add your
106   super-user to the 'FairphoneSoftwareTeam' group.
107
108 ## API Documentation
109
110 The Hiccup REST API documentation is created automatically using
111 [drf_yasg](https://github.com/axnsan12/drf-yasg) and
112 [swagger2markup](https://github.com/Swagger2Markup/swagger2markup).
113
114 It can be generated using tox:
115
116     (hiccupenv) $ tox -e docs
117
118 The generated documentation file can be found under
119 `documentation/api-endpoints.md`.
120
121 It is also possible to create an HTML version of the docs. Make sure you
122 have asciidoctor installed:
123
124     (hiccupenv) $ sudo apt install asciidoctor
125
126 Then generate the html docs using tox:
127
128     (hiccupenv) $ tox -e docs-html
129
130 The generated documentation file can be found under
131 `documentation/api-endpoints.html`.
132
133
134 ## Development
135
136 ### Coding Style
137
138 We follow the
139 [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
140
141 ### Setup
142
143 We use tox to both test and validate the code quality:
144
145     (hiccupenv) $ pip install -r requirements-dev.txt
146
147 #### Testing
148
149 Simply run `tox` to test your changes in the supported environments:
150
151     (hiccupenv) $ tox
152
153 To get an overview of the test coverage run:
154
155     (hiccupenv) $ tox -e coverage
156
157 To generate HTML coverage reports (saved to `htmlcov/`):
158
159      (hiccupenv) $ tox -e coverage-html
160
161 #### Linters and Formatters
162
163 To run the linters (flake8 and pylint) on all files:
164
165     (hiccupenv) $ tox -e linters
166
167 To run flake8 on only the diff with upstream:
168
169     (hiccupenv) $ git diff origin/master ./**/*py | flake8 --diff
170
171 We use the [black formatter](https://github.com/ambv/black) to check the
172 format of the code. To format a single file in place run:
173
174     (hiccupenv) $ black file.py
175
176 To run the formatter over all python files run:
177
178     (hiccupenv) $ git ls-files '*.py' | xargs black
179
180 Before committing a patchset, you are kindly asked to run the linting tools
181 ([flake8](http://flake8.pycqa.org/en/latest/) and
182 [pylint](https://pylint.readthedocs.io/en/latest/))
183 and format the code. For both linters and formatter, git pre-commit hooks
184 can be set up. To activate, copy the pre-commit script that calls all
185 scripts in `tools/hooks/pre-commit.d` to the `.git/hooks`
186 folder and make it executable:
187
188     (hiccupenv) $ cp tools/hooks/pre-commit .git/hooks/pre-commit
189     (hiccupenv) $ chmod +x .git/hooks/pre-commit
190
191 To prevent commits when the flake8 check fails the *strict* option can be
192 set to true:
193
194     (hiccupenv) $ git config --bool flake8.strict true
195
196 ### Branching structure
197
198 The `production` branch reflects the codebase currently running on the production server. New
199 changes should be pushed for review to the `master` branch. Every version that is merged into the
200 `master` branch has to be buildable. From there they can be merged into the `production` branch to
201 integrate the changes in the running server.
202
203
204 ## License
205
206 Copyright 2018 Fairphone B.V.
207
208 The project is made available under the terms of the Apache 2.0 license.
209 See [LICENSE](LICENSE) for details.