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 webtrees 2.0, use the `master` branch 13* For the latest webtrees 1.7.*, use the `1.7` branch 14 15Before submitting a pull request make sure you have [tested the code](#how-to-test) 16and [followed the coding conventions](#coding-conventions). 17 18Please read more about [setting up your environment](#how-to-setup-a-development-environment) for development. 19 20## How to start 21 22You can start contributing by 23 24* submitting patches or features 25* writing tests to [increase the test coverage](https://coveralls.io/github/fisharebest/webtrees?branch=master) 26* creating or updating [translations](#translations) 27* Join our slack. The invitation link will be updated on this line. 28* Help us maintaining our github page from the repository [webtrees.github.io](https://github.com/webtrees/webtrees.github.io). 29 30## How to setup a development environment 31 32You will need three tools, in addition to the requirements of a live installation. 33 34* `git` - to fetch the latest development code, merge changes, create pull requests, etc. 35* [`composer`](https://getcomposer.org) - to install PHP dependencies, build releases, and run tests. 36* [`npm`](https://nodejs.org/en/download/package-manager) - to install CSS/JS dependencies and create portable/minified `.css` / `.js` files. 37 38You 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. 39 40If 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". 41 42### GIT 43 44The project has been running for many years, and has a lot of history. 45This means that the full repository is over 600MB. 46 47If you are only interested in the latest version of the code, you can use a 48"shallow clone", which is about 30MB. 49 50Use `git clone --depth 1 https://github.com/fisharebest/webtrees`. 51 52### Composer 53 54The instructions below assume you have created an alias/shortcut for `composer`. 55If not, you'll need to replace `composer` with `php /path/to/your/copy/of/composer.phar`. 56 57* You would usually run `composer install` before starting any develoment. 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. 58 59* 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`. 60 61### NPM 62 63* 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`. 64 65## Third-party libraries and compiled files in the source tree 66 67For historic reasons, we include certain third-party libraries and compiled 68files in our source tree. This is usually considered to be bad practice. 69We do it because we have a large number of testers and users who have become 70accustomed to downloading the latest source code and running it without any build step. 71 72We include the non-development PHP libraries from `/vendor`. 73These are created using the command `composer install --no-dev`. 74 75We include the compiled JS and CSS assets from `/public/{css,js}`). 76These are created using the command `npm run production`. 77 78 79## Creating a pull request 80 81[TODO] 82 83 84 851. Fork and clone the repository 862. Run `composer install` to update the PHP dependencies. 873. Run `npm install` to update the JS and HTML files. 884. Run `php -S localhost:8080` and open your browser at [localhost:8080](http://localhost:8080) 895. Go through the install process 90 91## How to test 92 93Install PHPUnit by running `composer install` 94 95Then run the tests with `vendor/bin/phpunit` 96 97## Coding conventions 98 99Your code should follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) Extended coding style guide. 100 101Please do not contribute your IDE directories (e.g. `.idea` or `.vscode`). 102 103## Translations 104 105There is a [translators forum](http://webtrees.net/index.php/en/forum/8-translation) where you can discuss any issues relating to translation. 106 107Updates to translations should be made at [translate.webtrees.net](https://translate.webtrees.net). 108Changes made there will be pushed to webtrees git repository periodically and will be available 109on the development version of webtrees. They will be included in the next release of webtrees. 110 111