diff --git a/docs/contributions/index.rst b/docs/contributions/index.rst index 21da32ec2..620432d57 100644 --- a/docs/contributions/index.rst +++ b/docs/contributions/index.rst @@ -10,6 +10,19 @@ Contributions * +Thank you for considering contributing to the this project. We welcome contributions from everyone. +Before you start contributing, please read the following guidelines. They will help you to understand +the different ways you can contribute to the project. And this already starts with reporting an issue. + +Report an issue +=============== + +If you find a bug in the code, or have a suggestion for a new feature, please report it in the issue tracker. +This will help us to understand the problem you are facing. This will also make sure that you are not working +on something that might be rejected later. Please use the issue templates to report the issue. + +Now that you have reported the issue, you can start working on the issue. For bugs its always good to have a :ref:`failing test `. +to reproduce the issue. Clone the mono repository ========================= @@ -34,5 +47,28 @@ For instance, to run the pre-commit checks, you can run:: make PHP_BIN=php pre-commit-test -Submit a Pull Request -===================== +Submit changes (Pull Request) +============================= + +To submit a change, you need to create a pull request against the mono repository. Pull requests must +always target the ``main`` branch. We will not accept pull requests against other branches unless discussed +with the maintainers. The pull request should pass the tests and checks. you can run the checks locally like described +in :ref:`Run the tests `. + +If all checks pass, the pull request +will be reviewed, we try to do this as fast as possible, but as this is a community project, it might take +while before we can review your pull request. + +Documentation +============= + +As this is a documentation project, we also welcome contributions to the documentation. If you find a typo or an +error in the documentation, please report it in the issue tracker. If you want to fix it yourself, you can create a pull +request with the changes. We will review the changes and merge them if they are correct. + +Our documentation is written in reStructuredText and built with phpDocumentor. And can be found in the ``docs`` directory. + +Need help? +========== + +If you need help with contributing, please ask in the issue tracker. We are happy to help you with your contribution. diff --git a/docs/contributions/writing-tests.rst b/docs/contributions/writing-tests.rst new file mode 100644 index 000000000..55cb79d70 --- /dev/null +++ b/docs/contributions/writing-tests.rst @@ -0,0 +1,39 @@ +============= +Writing tests +============= + +This page will help you to understand how to write tests to report a bug or cover a new feature. +In this project we have 3 levels of tests: + +Integration tests: + This level of tests allow you to test the whole process from parsing to rendering. Integration tests are + not split as the other packages are. They are located in the ``tests/Integration/tests`` directory. and do exist + of one or more input files and the expected output. They might even have their own configuration file if that's required. + +Functional tests: + Functional tests are located in the ``tests/Functional`` directory. They cover individual elements of the processed + input. They do exist of one input file and the expected output. As they do not cover the whole process of parsing to + rendering, they cannot be used to test complex transformations. If you have a more complex use case you should have + a look at the integration tests. + +Unit tests: + Sometimes it's enough to test a single class in isolation. The unittests are part of the packages the test subject is + located in. They are located in the ``tests`` directory. The tests are named after the class they are testing. + +Integration tests +================= + +The integration tests can be seen as the easies way to write tests, as they are just like your normal use case. No internal +knowledge of the parser or renderer is required. You just need to know what you want to test and how the input and output +should look like. To create a new test you need to create a new directory in the ``tests/Integration/tests`` directory. +The name of the directory should be the name of the test. The directory should contain at least one input file and one +output file. Each test should have at least in index file. + +To make the output file more stable you can must use the following format:: + + +

Your output here

+ + +The content start and end tags are used to extract the content from the output file. This will isolate the content from +the rest of the output file. If you need to test the whole output file you should put your test in ``tests/Integration/tests-full``.