1# How to contribute 2 3Thanks for taking the time to contribute! 4 5The following is a set of guidelines for contributing to Webtrees. These are mostly guidelines, not rules. 6Use your best judgment, and feel free to propose changes to this document in a pull request. 7 8## How to submit a patch or feature 9 10If you want to submit a patch or feature, please create a pull request on Github. There are different branches for different versions of webtrees: 11 12* For the current version (2.1), use the `main` branch 13* For 2.0, use the `2.0` branch (security issues only) 14* For 1.7, use the `1.7` branch (security issues only) 15 16Before submitting a pull request make sure you have [tested the code](#how-to-test) 17and [followed the coding conventions](#coding-conventions). 18 19Please read more about [setting up your environment](#how-to-setup-a-development-environment) for development. 20 21## How to start 22 23You can start contributing by 24 25* submitting patches or features 26* writing tests to [increase the test coverage](https://coveralls.io/github/fisharebest/webtrees?branch=master) 27* creating or updating [translations](#translations) 28* Join our slack. The invitation link will be updated on this line. 29* Help us maintaining our github page from the repository [webtrees.github.io](https://github.com/webtrees/webtrees.github.io). 30 31## How to setup a development environment 32 33You will need three tools, in addition to the requirements of a live installation. 34 35* `git` - to fetch the latest development code, merge changes, create pull requests, etc. 36* [`composer`](https://getcomposer.org) - to install PHP dependencies, build releases, and run tests. 37* [`npm`](https://nodejs.org/en/download/package-manager) - to install CSS/JS dependencies and create portable/minified `.css` / `.js` files. 38 39You do not need to understand the details of `composer` and `npm`. You just need to be able to type a few commands at a console. 40 41If you are going to submit your work to the project, you will need a basic understanding of `git`. The workflow for using git is covered below in the section on "Pull Requests". 42 43### GIT 44 45The project has been running for many years, and has a lot of history. 46This means that the full repository is over 600MB. 47 48If you are only interested in the latest version of the code, you can use a 49"shallow clone", which is about 30MB. 50 51Use `git clone --depth 1 https://github.com/fisharebest/webtrees`. 52 53### Composer 54 55The instructions below assume you have created an alias/shortcut for `composer`. 56If not, you'll need to replace `composer` with `php /path/to/your/copy/of/composer.phar`. 57 58* You would usually run `composer install` before starting any development. This loads all the development tools, including the PHP debug bar, the build scripts, the analysis and testing tools. You would then run `composer install --no-dev` before committing any changes. 59 60* You can use a "pre-commit hook" to run checks on your code before you commit them to your local repository. To do this, rename the file `.git/hooks/pre-commit.sample` to `.git/hooks/pre-commit` and then add this line at the end of the file: `composer webtrees:pre-commit-hook`. 61 62### NPM 63 64* After modifying any CSS or JS files, you'll need to rebuild the files in `public/js` and `public/css`. You do this with the command `npm run production`. 65 66## Third-party libraries and compiled files in the source tree 67 68For historic reasons, we include certain third-party libraries and compiled 69files in our source tree. This is usually considered to be bad practice. 70We do it because we have a large number of testers and users who have become 71accustomed to downloading the latest source code and running it without any build step. 72 73We include the non-development PHP libraries from `/vendor`. 74These are created using the command `composer install --no-dev`. 75 76We include the compiled JS and CSS assets from `/public/{css,js}`). 77These are created using the command `npm run production`. 78 79 80## Creating a pull request 81 82[TODO] 83 84 85 861. Fork and clone the repository 872. Run `composer install` to update the PHP dependencies. 883. Run `npm install` to update the JS and HTML files. 894. Run `php -S localhost:8080` and open your browser at [localhost:8080](http://localhost:8080) 905. Go through the install process 91 92## How to test 93 94Install PHPUnit by running `composer install` 95 96Then run the tests with `vendor/bin/phpunit` 97 98## Coding conventions 99 100Your code should follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) Extended coding style guide. 101 102Please do not contribute your IDE directories (e.g. `.idea` or `.vscode`). 103 104## Translations 105 106There is a [translators forum](http://webtrees.net/index.php/en/forum/8-translation) where you can discuss any issues relating to translation. 107 108Updates to translations should be made at [translate.webtrees.net](https://translate.webtrees.net). 109Changes made there will be pushed to webtrees git repository periodically and will be available 110on the development version of webtrees. They will be included in the next release of webtrees. 111 112