CONTRIBUTING.md 3.05 KB
Newer Older
Filipe Laíns's avatar
Filipe Laíns committed
1
2
# Contributing

3
4
Patches should be sent to the [aur-dev@lists.archlinux.org][1] mailing list
or included in a merge request on the [aurweb repository][2].
Filipe Laíns's avatar
Filipe Laíns committed
5

6
Before sending patches, you are recommended to run `flake8` and `isort`.
Filipe Laíns's avatar
Filipe Laíns committed
7

8
9
You can add a git hook to do this by installing `python-pre-commit` and running
`pre-commit install`.
Filipe Laíns's avatar
Filipe Laíns committed
10

11
[1]: https://lists.archlinux.org/listinfo/aur-dev
Kevin Morris's avatar
Kevin Morris committed
12
[2]: https://gitlab.archlinux.org/archlinux/aurweb
13
14
15

### Coding Guidelines

16
17
18
DISCLAIMER: We realise the code doesn't necessarily follow all the rules.
This is an attempt to establish a standard coding style for future
development.
19

20
21
22
23
24
25
1. All source modified or added within a patchset **must** maintain equivalent
   or increased coverage by providing tests that use the functionality
2. Please keep your source within an 80 column width
3. Use four space indentation
4. Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
5. DRY: Don't Repeat Yourself
Kevin Morris's avatar
Kevin Morris committed
26
27
28
6. All code should be tested for good _and_ bad cases (see [test/README.md][3])

[3]: https://gitlab.archlinux.org/archlinux/aurweb/-/blob/master/test/README.md
29
30

Test patches that increase coverage in the codebase are always welcome.
Kevin Morris's avatar
Kevin Morris committed
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

### Coding Style

We use the `flake8` and `isort` tools to manage PEP-8 coherenace and
import ordering in this project.

There are plugins for editors or IDEs which automate this process. Some
example plugins:

- [tell-k/vim-autopep8](https://github.com/tell-k/vim-autopep8)
- [fisadev/vim-isort](https://github.com/fisadev/vim-isort)
- [prabirshrestha/vim-lsp](https://github.com/prabirshrestha/vim-lsp)

See `setup.cfg` for flake8 and isort specific rules.

Note: We are planning on switching to [psf/black](https://github.com/psf/black).
For now, developers should ensure that flake8 and isort passes when submitting
merge requests or patch sets.

### Development Environment

To get started with local development, an instance of aurweb must be
brought up. This can be done using the following sections:

- [Using Docker](#using-docker)
- [Using INSTALL](#using-install)

There are a number of services aurweb employs to run the application
in its entirety:

- ssh
- cron jobs
- starlette/fastapi asgi server

Project structure:

- `./aurweb`: `aurweb` Python package
- `./templates`: Jinja2 templates
- `./docker`: Docker scripts and configuration files

#### Using Docker

Using Docker, we can run the entire infrastructure in two steps:

    # Build the aurweb:latest image
    $ docker-compose build

    # Start all services in the background
    $ docker-compose up -d nginx

`docker-compose` services will generate a locally signed root certificate
at `./data/root_ca.crt`. Users can import this into ca-certificates or their
browser if desired.

Accessible services (on the host):

- https://localhost:8444 (python via nginx)
- https://localhost:8443 (php via nginx)
- localhost:13306 (mariadb)
- localhost:16379 (redis)

Docker services, by default, are setup to be hot reloaded when source code
is changed.

#### Using INSTALL

The [INSTALL](INSTALL) file describes steps to install the application on
bare-metal systems.