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* The PHP Debug Bar can set a large number of HTTP headers, and you may need to increase the size of buffers in your webserver configuration. There are some notes in the file `app/Http/Middleware/UseDebugbar.php`. 60 61* 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`. 62 63### NPM 64 65* 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`. 66 67## Third-party libraries and compiled files in the source tree 68 69For historic reasons, we include certain third-party libraries and compiled 70files in our source tree. This is usually considered to be bad practice. 71We do it because we have a large number of testers and users who have become 72accustomed to downloading the latest source code and running it without any build step. 73 74We include the non-development PHP libraries from `/vendor`. 75These are created using the command `composer install --no-dev`. 76 77We include the compiled JS and CSS assets from `/public/{css,js}`). 78These are created using the command `npm run production`. 79 80 81## Creating a pull request 82 83[TODO] 84 85 86 871. Fork and clone the repository 882. Run `composer install` to update the PHP dependencies. 893. Run `npm install` to update the JS and HTML files. 904. Run `php -S localhost:8080` and open your browser at [localhost:8080](http://localhost:8080) 915. Go through the install process 92 93## How to test 94 95Install PHPUnit by running `composer install` 96 97Then run the tests with `vendor/bin/phpunit` 98 99## Coding conventions 100 101Your code should follow the [PSR-12](https://www.php-fig.org/psr/psr-12/) Extended coding style guide. 102 103Please do not contribute your IDE directories (e.g. `.idea` or `.vscode`). 104 105## Translations 106 107There is a [translators forum](http://webtrees.net/index.php/en/forum/8-translation) where you can discuss any issues relating to translation. 108 109Updates to translations should be made at [translate.webtrees.net](https://translate.webtrees.net). 110Changes made there will be pushed to webtrees git repository periodically and will be available 111on the development version of webtrees. They will be included in the next release of webtrees. 112 113