From c7c9ab71ff507bb2a2b42f1f793dc752b2272906 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Fri, 26 Jun 2020 21:22:54 +0200 Subject: [PATCH 1/4] Created first draft of the contributing file --- CONTRIBUTING.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9dcb330a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +This file will guide you through the process of getting to project up and running, in order to provide coding contributions. + +You will also see how to ensure the code fulfills the expected code checks, and how to end up creating a pull request. + +## System dependencies + +The project provides all its dependencies as docker containers through a docker-compose configuration. + +Because of this, the only actual dependencies are [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/install/). + +## Setting up the project + +The first thing you need to do is fork the repository, and clone it in your local machine. + +Then you will have to follow these steps: + +* Copy all files with `.local.php.dist` extension from `config/autoload` by removing the dist extension. + + For example the `common.local.php.dist` file should be copied as `common.local.php`. + +* Copy the file `docker-compose.override.yml.dist` by also removing the `dist` extension. +* Start-up the project by running `docker-compose up`. + + The first time this command is run, it will create several containers that are used during development, and may tike some time. + + It will also create some empty databases and install the project dependencies with composer. + +* Run `./indocker bin/cli db:create` to create an empty database. +* Run `./indocker bin/cli db:migrate` to get database migrations up to date. +* Run `./indocker bin/cli api-key:generate` to get your first API key generated. + +Once you finish this, you will have the project exposed in ports `8080` through nginx+php-fpm and `8000` through swoole. + +> Note: The `indocker` shell script is a helper used to run commands inside the main docker container. + +## Running code checks + +* Run `./indocker composer cs` to check coding styles are fulfilled. +* Run `./indocker composer cs:fix` to fix coding styles (some may not be fixeable from the CLI) +* Run `./indocker composer stan` to check the code with phpstan. This tool is the closest you have to "compile" PHP and verify everything would work as expected. +* Run `./indocker composer test:unit` to run the unit tests. +* Run `./indocker composer test:db` to run integration tests with the database. + + This command runs the same test suite against all supported database engines. If you just want to run one of them, you can add one of `:sqlite`, `:mysql`, `:maria`, `:postgres`, `:mssql` to the command to run just one of them. + + For example, `test:db:postgres`. + +* Run `./indocker composer test:api` to run API E2E tests. For these, the MySQL database engine is used. + +> Note: Due to some limitations in the tooling used by shlink, the testing databases need to exist first, both for db and api tests (except sqlite). +> +> However, they just need to be created empty, with no tables. Also, once created, they are automatically reset before each execution. +> +> The testing database is always called `shlink_testing`. You can create it using the database client of your choice. [DBeaver](https://dbeaver.io/) is a good multi-platform desktop database client which supports all the engines supported by shlink. + +## Pull request process From 035743ef6aaeae3cf085ab56ca05ea9438df4138 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sat, 27 Jun 2020 10:34:26 +0200 Subject: [PATCH 2/4] Added minor imporovements to CONTRIBUTING file --- CONTRIBUTING.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9dcb330a..4b335516 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ # Contributing -This file will guide you through the process of getting to project up and running, in order to provide coding contributions. +This file will guide you through the process of getting to project up and running, in case you want to provide coding contributions. -You will also see how to ensure the code fulfills the expected code checks, and how to end up creating a pull request. +You will also see how to ensure the code fulfills the expected code checks, and how to creating a pull request. ## System dependencies @@ -23,11 +23,11 @@ Then you will have to follow these steps: * Copy the file `docker-compose.override.yml.dist` by also removing the `dist` extension. * Start-up the project by running `docker-compose up`. - The first time this command is run, it will create several containers that are used during development, and may tike some time. + The first time this command is run, it will create several containers that are used during development, so it may take some time. It will also create some empty databases and install the project dependencies with composer. -* Run `./indocker bin/cli db:create` to create an empty database. +* Run `./indocker bin/cli db:create` to create the initial database. * Run `./indocker bin/cli db:migrate` to get database migrations up to date. * Run `./indocker bin/cli api-key:generate` to get your first API key generated. @@ -38,21 +38,24 @@ Once you finish this, you will have the project exposed in ports `8080` through ## Running code checks * Run `./indocker composer cs` to check coding styles are fulfilled. -* Run `./indocker composer cs:fix` to fix coding styles (some may not be fixeable from the CLI) -* Run `./indocker composer stan` to check the code with phpstan. This tool is the closest you have to "compile" PHP and verify everything would work as expected. +* Run `./indocker composer cs:fix` to fix coding styles (some may not be fixable from the CLI) +* Run `./indocker composer stan` to statically analyze the code with [phpstan](https://phpstan.org/). This tool is the closest to "compile" PHP and verify everything would work as expected. * Run `./indocker composer test:unit` to run the unit tests. -* Run `./indocker composer test:db` to run integration tests with the database. +* Run `./indocker composer test:db` to run the database integration tests. - This command runs the same test suite against all supported database engines. If you just want to run one of them, you can add one of `:sqlite`, `:mysql`, `:maria`, `:postgres`, `:mssql` to the command to run just one of them. + This command runs the same test suite against all supported database engines. If you just want to run one of them, you can add one of `:sqlite`, `:mysql`, `:maria`, `:postgres`, `:mssql` at the end of the command. For example, `test:db:postgres`. * Run `./indocker composer test:api` to run API E2E tests. For these, the MySQL database engine is used. +* Run `./indocker composer infect:test` ti run both unit and database tests (over sqlite) and then apply mutations to them with [infection](https://infection.github.io/). -> Note: Due to some limitations in the tooling used by shlink, the testing databases need to exist first, both for db and api tests (except sqlite). +> Note: Due to some limitations in the tooling used by shlink, the testing databases need to exist beforehand, both for db and api tests (except sqlite). > -> However, they just need to be created empty, with no tables. Also, once created, they are automatically reset before each execution. +> However, they just need to be created empty, with no tables. Also, once created, they are automatically reset before every new execution. > -> The testing database is always called `shlink_testing`. You can create it using the database client of your choice. [DBeaver](https://dbeaver.io/) is a good multi-platform desktop database client which supports all the engines supported by shlink. +> The testing database is always called `shlink_test`. You can create it using the database client of your choice. [DBeaver](https://dbeaver.io/) is a good multi-platform desktop database client which supports all the engines supported by shlink. ## Pull request process + + From d234e114db3c17b16a7243de1bfaa5bef01df9ac Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sat, 27 Jun 2020 10:41:29 +0200 Subject: [PATCH 3/4] Added description on how to create pull requests to CONTRIBUTING file --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b335516..da4b26c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,6 +49,7 @@ Once you finish this, you will have the project exposed in ports `8080` through * Run `./indocker composer test:api` to run API E2E tests. For these, the MySQL database engine is used. * Run `./indocker composer infect:test` ti run both unit and database tests (over sqlite) and then apply mutations to them with [infection](https://infection.github.io/). +* Run `./indocker composer ci` to run all previous commands together. This command is run during the project's continuous integration. > Note: Due to some limitations in the tooling used by shlink, the testing databases need to exist beforehand, both for db and api tests (except sqlite). > @@ -58,4 +59,8 @@ Once you finish this, you will have the project exposed in ports `8080` through ## Pull request process +In order to provide pull requests to this project, you should always start by creating a new branch, where you will make all desired changes. +The base branch should always be `develop`, and the target branch for the pull request should also be `develop`. + +Before your branch can be merged, all the checks described in [Running code checks](#running-code-checks) have to be passing. You can verify that manually by running `./indocker composer ci`, or wait for the build to be run automatically after the pull request is created. From bf1c6e3d4333741828d4f84be843d2e7446e7613 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sat, 27 Jun 2020 10:43:43 +0200 Subject: [PATCH 4/4] Referenced CONTRIBUTING doc from README --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f8a1990a..cd3ba8ea 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ A PHP-based self-hosted URL shortener that can be used to serve shortened URLs u > This document references Shlink 2.x. If you are using an older version and want to upgrade, follow the [UPGRADE](UPGRADE.md) doc. +> If you are trying to find out how to run the project in development mode or how to provide contributions, read the [CONTRIBUTING](CONTRIBUTING.md) doc. + ## Table of Contents - [Installation](#installation)