Contributing to the pcs project

Running pcs and its test suite

Using Python virtual environment (pyenv) is highly recommended, as it provides means of isolating development packages from system-wide packages. It allows to install specific versions of python packages, which pcs depends on, independently on the rest of the system.
In this tutorial, we choose to create a pyenv in ~/pyenvs/pcs directory.
Create a base directory: mkdir ~/pyenvs
Create a pyenv: python3 -m venv --system-site-packages ~/pyenvs/pcs
To activate the pyenv, run source ~/pyenvs/pcs/bin/activate or . ~/pyenvs/pcs/bin/activate
To deactivate the pyenv, run deactivate

Go to pcs directory.
If you created a pyenv according to the previous section, make sure it is activated.
Run ./autogen.sh.
- This generates configure script based on configure.ac file.
- It requires an annotated tag to be present in git repository. The easiest way to acomplish that is to add the upstream pcs repository as a remote repository.
Run ./configure.
- This checks all the dependencies and creates various files (including Makefile files) based on theirs *.in templates.
- To list available options and their description, run ./configure -h.
- Recommended setup for development is to run ./configure --enable-local-build --enable-dev-tests --enable-destructive-tests --enable-concise-tests --enable-parallel-tests
Run make.
- This downloads and installs dependencies, such as python modules and rubygems.

To run all the tests, type make check.
- You may run specific tests like this:
  - make black_check
  - make mypy
  - make pylint
  - make tests_tier0
  - make tests_tier1
  - make pcsd-tests
- To run specific tests from python test suite, type pcs_test/suite <test>
When make check passes, you may want to run make distcheck.
- This generates a distribution tarball and checks it.
- The check is done by extracting files from the tarball, running ./configure and make check.
- Note, that ./configure is run with no options, so it requires dependencies to be installed system wide. This can be overriden by running make distcheck DISTCHECK_CONFIGURE_FLAGS='<flag>...'.
- The point of this test is to make sure all necessary files are present in the tarball.
To run black code formater, type make black.

To create a tarball for distribution, run make dist.
The user of the tarball is supposed to run ./configure with options they see fit. Then, they can run make with any target they need.

All system-dependent paths must be located in pcs/settings.py.in and pcsd/settings.rb.in files.
Do not forget to run ./configure after changing any *.in file.
All files meant to be distributed must be listed in EXTRA_DIST variable in Makefile.am file in specific directory (pcs, pcs/pcs, pcs/pcs_tests, pcs/pcsd), with the exception of files created by autoconf / automake.