Merge pull request #877 from phpDocumentor/docs-contributing

[DOCS] Add more contribution guidelines

Author: jaapio

.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

.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."

.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

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 <writing-tests>`.
+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 <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.

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::
+
+   <!-- content start -->
+       <p>Your output here</p>
+    <!-- content end -->
+
+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``.