umap/docs/contributing.md

105 lines
3.3 KiB
Markdown
Raw Normal View History

2016-09-10 02:44:46 -05:00
# Contributing
2023-11-28 08:54:11 -06:00
So you want to contribute to uMap? Great news 🙌
2023-11-28 08:54:11 -06:00
We've put together this document so you have a brief overview of how things work.
You can help on different areas: translation, bug triage, documentation and development.
2023-11-28 08:54:11 -06:00
## Translating
2023-11-28 08:54:11 -06:00
uMap is translated to more than 50 languages! The translation is managed through [Transifex](https://www.transifex.com/openstreetmap/umap/). You will need an account to get started, and then you'll be able to translate easily.
2023-11-28 08:54:11 -06:00
## Bug Triage
2023-11-28 08:54:11 -06:00
You are very welcome to help us triage [uMap issues](https://github.com/umap-project/umap/issues). Don't hesitate to help other users by answering questions, give your point of view in discussions and just report bugs!
2023-11-28 08:54:11 -06:00
## Reporting a bug
2023-11-28 08:54:11 -06:00
If you've encountered a bug, don't hesitate to tell us about it. The best way to do this is by [opening a ticket on the bug tracker](https://github.com/umap-project/umap/issues/new/choose). But please, first, [have a look around](https://github.com/umap-project/umap/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) to see if other users already reported something 😅
2023-11-28 08:54:11 -06:00
## Hacking on the code
2023-11-28 08:54:11 -06:00
Following the [installation instructions](install.md) should get you started to hack on the code.
2023-12-05 09:18:10 -06:00
### Installing dev dependencies
2023-12-05 09:18:10 -06:00
To be sure to install all the dev dependencies, and have everything working locally.
2023-12-05 09:18:10 -06:00
```bash
make develop
```
2023-12-15 10:43:13 -06:00
#### JavaScript
For JavaScript, here is the tooling we use:
- Format your code with [Prettier](https://prettier.io/)
- Be sure to configure your editor to insert new lines at the end of files.
2023-12-05 09:18:10 -06:00
### Hack!
You can now do your changes in a specific branch, and when you're ready you can open a pull-request for us to review.
2023-12-15 10:43:13 -06:00
### Running tests
2023-12-05 09:18:10 -06:00
Multiple tests suites are in use in the project. You can run all the tests by using:
2023-12-05 09:18:10 -06:00
```
make test
```
This will run JavaScript and Python unittests + Playwright integration tests
2023-12-15 10:43:13 -06:00
#### Python unit tests
```bash
pytest . --ignore umap/tests/integration
```
By default, the tests are run in parallel to reduce the time taken to run them. You can run them in serial mode by using the `-n1` option.
If you only want to run one test, you can add `-k specific-test-name` to the command line.
All the tests are run when you're creating a pull request, to avoid regressions.
2023-12-15 10:43:13 -06:00
#### Integration tests
```bash
pytest umap/tests/integration
```
The tests are using [Playwright](https://playwright.dev), which spawns a headless browser and runs the tests on it.
If the tests are failing, it might be useful to step trough the tests in the browser. This will let you go step by step with a debugger, so you can see what is happening on a real browser.
```bash
PWDEBUG=1 pytest --headed -n1 -k specific-test-name
```
#### JS tests
```bash
make testjs
```
These tests are located in `umap/static/test`, and we are currently using a mocha test runner.
2023-12-05 09:18:10 -06:00
### Merging rules
Pull requests need to be accepted by one maintainer of the project. Please be patient, we try to do our best, but it sometimes takes time.
## Update the translations
Install needed tools:
apt install gettext transifex-client
Pull the translations from transifex website:
tx pull -f
Then you will need to update binary files with command:
2020-04-26 10:46:28 -05:00
make compilemessages
Done. You can now review and commit modified/added files.