Skip to content

Commit 0f524b8

Browse files
jaapiojaapio
authored
Merge pull request #877 from phpDocumentor/docs-contributing
[DOCS] Add more contribution guidelines
2 parents f235c57 + f60570b commit 0f524b8

File tree

5 files changed

+119
-2
lines changed

5 files changed

+119
-2
lines changed

‎.github/ISSUE_TEMPLATE/bug.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: "Bug report 🐛"
2+
description: "If something isn't working as expected 🤔."
3+
title: "[Bug]: "
4+
labels: ["bug", "triage"]
5+
6+
body:
7+
- type: "textarea"
8+
attributes:
9+
label: "Summary"
10+
description: "Please describe your problem here"
11+
validations:
12+
required: true
13+
14+
- type: "textarea"
15+
attributes:
16+
label: "Code snippet that reproduces the problem"
17+
description: |
18+
Please provide a minimal code snippet that reproduces the problem. If you have a larger code example,
19+
please provide a link to a repository or create a pull request that introduces a failing test case.
20+
21+
- type: "textarea"
22+
attributes:
23+
label: "Expected output"
24+
description: "What did you expect to happen?"
25+
validations:
26+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: "Support Question"
4+
url: "https://github.com/orgs/phpDocumentor/discussions"
5+
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‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: "Feature request 🚀"
2+
description: "I have a suggestion (and may want to implement it 🙂)!"
3+
labels: ["feature", "triage"]
4+
5+
body:
6+
- type: "textarea"
7+
attributes:
8+
label: "Feature request"
9+
description: "Please provide a clear description of what problem you are trying to solve and how would you want it to be solved."
10+
validations:
11+
required: true

‎docs/contributions/index.rst‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,19 @@ Contributions
1010

1111
*
1212

13+
Thank you for considering contributing to the this project. We welcome contributions from everyone.
14+
Before you start contributing, please read the following guidelines. They will help you to understand
15+
the different ways you can contribute to the project. And this already starts with reporting an issue.
16+
17+
Report an issue
18+
===============
19+
20+
If you find a bug in the code, or have a suggestion for a new feature, please report it in the issue tracker.
21+
This will help us to understand the problem you are facing. This will also make sure that you are not working
22+
on something that might be rejected later. Please use the issue templates to report the issue.
23+
24+
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>`.
25+
to reproduce the issue.
1326

1427
Clone the mono repository
1528
=========================
@@ -34,5 +47,28 @@ For instance, to run the pre-commit checks, you can run::
3447

3548
make PHP_BIN=php pre-commit-test
3649

37-
Submit a Pull Request
38-
=====================
50+
Submit changes (Pull Request)
51+
=============================
52+
53+
To submit a change, you need to create a pull request against the mono repository. Pull requests must
54+
always target the ``main`` branch. We will not accept pull requests against other branches unless discussed
55+
with the maintainers. The pull request should pass the tests and checks. you can run the checks locally like described
56+
in :ref:`Run the tests <run-the-tests>`.
57+
58+
If all checks pass, the pull request
59+
will be reviewed, we try to do this as fast as possible, but as this is a community project, it might take
60+
while before we can review your pull request.
61+
62+
Documentation
63+
=============
64+
65+
As this is a documentation project, we also welcome contributions to the documentation. If you find a typo or an
66+
error in the documentation, please report it in the issue tracker. If you want to fix it yourself, you can create a pull
67+
request with the changes. We will review the changes and merge them if they are correct.
68+
69+
Our documentation is written in reStructuredText and built with phpDocumentor. And can be found in the ``docs`` directory.
70+
71+
Need help?
72+
==========
73+
74+
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‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
=============
2+
Writing tests
3+
=============
4+
5+
This page will help you to understand how to write tests to report a bug or cover a new feature.
6+
In this project we have 3 levels of tests:
7+
8+
Integration tests:
9+
This level of tests allow you to test the whole process from parsing to rendering. Integration tests are
10+
not split as the other packages are. They are located in the ``tests/Integration/tests`` directory. and do exist
11+
of one or more input files and the expected output. They might even have their own configuration file if that's required.
12+
13+
Functional tests:
14+
Functional tests are located in the ``tests/Functional`` directory. They cover individual elements of the processed
15+
input. They do exist of one input file and the expected output. As they do not cover the whole process of parsing to
16+
rendering, they cannot be used to test complex transformations. If you have a more complex use case you should have
17+
a look at the integration tests.
18+
19+
Unit tests:
20+
Sometimes it's enough to test a single class in isolation. The unittests are part of the packages the test subject is
21+
located in. They are located in the ``tests`` directory. The tests are named after the class they are testing.
22+
23+
Integration tests
24+
=================
25+
26+
The integration tests can be seen as the easies way to write tests, as they are just like your normal use case. No internal
27+
knowledge of the parser or renderer is required. You just need to know what you want to test and how the input and output
28+
should look like. To create a new test you need to create a new directory in the ``tests/Integration/tests`` directory.
29+
The name of the directory should be the name of the test. The directory should contain at least one input file and one
30+
output file. Each test should have at least in index file.
31+
32+
To make the output file more stable you can must use the following format::
33+
34+
<!-- content start -->
35+
<p>Your output here</p>
36+
<!-- content end -->
37+
38+
The content start and end tags are used to extract the content from the output file. This will isolate the content from
39+
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``.

0 commit comments

Comments
 (0)