From eb19f0d26a016210b2be62ba6d96e1ca02efe17d Mon Sep 17 00:00:00 2001 From: Jaapio Date: Fri, 1 Mar 2024 14:28:32 +0100 Subject: [PATCH 1/2] [DOCS] Add more contribution guidelines --- docs/contributions/index.rst | 40 ++++++++++++++++++++++++++-- docs/contributions/writing-tests.rst | 39 +++++++++++++++++++++++++++ 2 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/contributions/writing-tests.rst 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``. From f60570bd3f251811c4747125adce355aa5b22306 Mon Sep 17 00:00:00 2001 From: Jaapio Date: Fri, 1 Mar 2024 14:58:08 +0100 Subject: [PATCH 2/2] Add issue templates --- .github/ISSUE_TEMPLATE/bug.yml | 26 ++++++++++++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 +++++ .github/ISSUE_TEMPLATE/feature.yaml | 11 +++++++++++ 3 files changed, 42 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature.yaml diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 000000000..5e0fc6d99 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,26 @@ +name: "Bug report 🐛" +description: "If something isn't working as expected 🤔." +title: "[Bug]: " +labels: ["bug", "triage"] + +body: + - type: "textarea" + attributes: + label: "Summary" + description: "Please describe your problem here" + validations: + required: true + + - type: "textarea" + attributes: + label: "Code snippet that reproduces the problem" + description: | + Please provide a minimal code snippet that reproduces the problem. If you have a larger code example, + please provide a link to a repository or create a pull request that introduces a failing test case. + + - type: "textarea" + attributes: + label: "Expected output" + description: "What did you expect to happen?" + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..ba2317084 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: "Support Question" + url: "https://github.com/orgs/phpDocumentor/discussions" + about: "We use GitHub issues only to discuss about bugs and new features. For this kind of questions about using the project, please use the discussions." diff --git a/.github/ISSUE_TEMPLATE/feature.yaml b/.github/ISSUE_TEMPLATE/feature.yaml new file mode 100644 index 000000000..828189c2f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.yaml @@ -0,0 +1,11 @@ +name: "Feature request 🚀" +description: "I have a suggestion (and may want to implement it 🙂)!" +labels: ["feature", "triage"] + +body: + - type: "textarea" + attributes: + label: "Feature request" + description: "Please provide a clear description of what problem you are trying to solve and how would you want it to be solved." + validations: + required: true