From 7df8476eb05a369204d958db26e45121183e1564 Mon Sep 17 00:00:00 2001 From: Konrad Abicht Date: Thu, 31 Oct 2024 10:04:54 +0100 Subject: [PATCH 1/4] introducing CONTRIBUTING.md also changed related files --- .github/ISSUE_TEMPLATE/incorrect-parsing.md | 6 +++--- .github/pull_request_template.md | 20 +------------------ CONTRIBUTING.md | 22 +++++++++++++++++++++ README.md | 1 + 4 files changed, 27 insertions(+), 22 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/incorrect-parsing.md b/.github/ISSUE_TEMPLATE/incorrect-parsing.md index f7962889..603fe442 100644 --- a/.github/ISSUE_TEMPLATE/incorrect-parsing.md +++ b/.github/ISSUE_TEMPLATE/incorrect-parsing.md @@ -8,10 +8,10 @@ assignees: '' --- - + - - PHP Version: - - PDFParser Version: + - PHP Version: + - PDFParser Version: ### Description: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a130ef15..fe9569ab 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,22 +11,4 @@ # Checklist for code / configuration changes -*In case you changed the code/configuration, please read each of the following checkboxes as they contain valuable information:* - -* [ ] Please add at least **one test case** (unit test, system test, ...) to demonstrate that the change is working. If existing code was changed, your tests cover these code parts as well. - By the way, you don't have to provide a full fledged PDF file to demonstrate a fix. Instead a unit test may be sufficient sometimes, - please have a look at [FontTest](https://github.com/smalot/pdfparser/blob/master/tests/PHPUnit/Unit/FontTest.php#L40) for example code. - Code changes without any tests are likely to be rejected. If you dont know how to write tests, no problem, tell us upfront and we may add them ourselves or discuss other ways. -* [ ] Please run **PHP-CS-Fixer** before committing, to confirm with our coding styles. See https://github.com/smalot/pdfparser/blob/master/.php-cs-fixer.php for more information about our coding styles. -* [ ] In case you **fix an existing issue**, please do one of the following: - * [ ] Write in this text something like `fixes #1234` to outline that you are providing a fix for the issue `#1234`. - * [ ] After the pull request was created, you will find on the right side a section called **Development**. There issues can be selected which will be closed after the your pull request got merged. -* [ ] In case you changed internal behavior or functionality, please check our documentation to make sure these changes are **documented properly**: https://github.com/smalot/pdfparser/tree/master/doc -* [ ] In case you want to discuss new ideas/changes and you are not sure, just create a pull request and mark it as **a draft** - (see [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) for more information). - This will tell us, that it is not ready for merge, but you want to discuss certain issues. - - +In [CONTRIBUTING.md] we provide important information for contributing. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..20c67294 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +# Contributing + +**Please read the following text before creating a pull request.** + +This project is organized and supported by community contributions and maintenance is done in our sparse time. +We welcome any pull request that adds/extends functionality. +However, we would point out that you are initially responsible for a contribution. +If you are new to pull requests see [Github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) for further information. +Please don't just throw code at us and expect us to handle it. +That being said, we will assist you and give feedback. + +## Important steps + +To make life easier for you and us, there is a continuous integration (CI) system that runs software tests and performs a number of other tasks. +The following points describe relevant preparations/inputs for the CI system. +All checks must be green or a pull request is not accepted. + +* If you add/change functionality add at least **one test case** (unit test, system test, ...) to demonstrate that your code is working. There is no need to provide a full fledged PDF file to demonstrate a fix. Instead a unit test may be sufficient sometimes, have a look at [FontTest](https://github.com/smalot/pdfparser/blob/master/tests/PHPUnit/Unit/FontTest.php#L40) for example code. + * :exclamation: **If you dont know how to write tell us upfront when opening the pull request and we may add them ourselves or discuss other ways**. Code changes without tests are very likely to be rejected. +* Fix reported coding style issues. We use **PHP-CS-Fixer** for that. See https://github.com/smalot/pdfparser/blob/master/.php-cs-fixer.php for more information about our coding styles. See [Developer.md](./doc/Developer.md) for further information. +* In case you **fix an existing issue**, refer to it in intro text of the pull request. In the following the correct Markdown syntax: `fixes #1234`. This example outlines that you are providing a fix for the issue `#1234`. +* [ ] In case **you changed internal behavior/functionality** check our documentation to make sure these changes are **documented properly**: https://github.com/smalot/pdfparser/tree/master/doc diff --git a/README.md b/README.md index ddffef99..b4cd2799 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ The `smalot/pdfparser` is a standalone PHP package that provides various tools t This library is under **active maintenance**. There is no active development by the author of this library (at the moment), but we welcome any pull request adding/extending functionality! +Consult [CONTRIBUTING.md](./CONTRIBUTING.md) for further information about how to contribute. ## Features From a8752ffad7287cc55adb433c3d856d2a8ba04f5b Mon Sep 17 00:00:00 2001 From: Konrad Abicht Date: Thu, 31 Oct 2024 10:09:42 +0100 Subject: [PATCH 2/4] mostly text refinements --- CONTRIBUTING.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20c67294..e0c7a32c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,7 +3,7 @@ **Please read the following text before creating a pull request.** This project is organized and supported by community contributions and maintenance is done in our sparse time. -We welcome any pull request that adds/extends functionality. +We welcome any pull request that contributes to the PDFParser (code, documentation, ...). However, we would point out that you are initially responsible for a contribution. If you are new to pull requests see [Github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) for further information. Please don't just throw code at us and expect us to handle it. @@ -16,7 +16,7 @@ The following points describe relevant preparations/inputs for the CI system. All checks must be green or a pull request is not accepted. * If you add/change functionality add at least **one test case** (unit test, system test, ...) to demonstrate that your code is working. There is no need to provide a full fledged PDF file to demonstrate a fix. Instead a unit test may be sufficient sometimes, have a look at [FontTest](https://github.com/smalot/pdfparser/blob/master/tests/PHPUnit/Unit/FontTest.php#L40) for example code. - * :exclamation: **If you dont know how to write tell us upfront when opening the pull request and we may add them ourselves or discuss other ways**. Code changes without tests are very likely to be rejected. + * :exclamation: **If you dont know how to write a test tell us upfront when opening the pull request and we may add them ourselves or discuss other ways**. This [Medium article](https://pguso.medium.com/a-beginners-guide-to-phpunit-writing-and-running-unit-tests-in-php-d0b23b96749f) might be a good point to start. Code changes without tests are very likely to be rejected. * Fix reported coding style issues. We use **PHP-CS-Fixer** for that. See https://github.com/smalot/pdfparser/blob/master/.php-cs-fixer.php for more information about our coding styles. See [Developer.md](./doc/Developer.md) for further information. -* In case you **fix an existing issue**, refer to it in intro text of the pull request. In the following the correct Markdown syntax: `fixes #1234`. This example outlines that you are providing a fix for the issue `#1234`. -* [ ] In case **you changed internal behavior/functionality** check our documentation to make sure these changes are **documented properly**: https://github.com/smalot/pdfparser/tree/master/doc +* In case you **fix an existing issue**, refer to it in the intro text of the pull request. In the following the correct Markdown syntax: `fixes #1234`. This example outlines that you are providing a fix for the issue `#1234`. +* In case **you changed internal behavior/functionality** check our documentation to make sure these changes are **documented properly**: https://github.com/smalot/pdfparser/tree/master/doc From 677573977b571898be60762dd69f535bb6996c8c Mon Sep 17 00:00:00 2001 From: Konrad Abicht Date: Tue, 5 Nov 2024 08:58:50 +0100 Subject: [PATCH 3/4] refined text (corrected grammar, ...) --- .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 28 +++++++++++++--------------- README.md | 2 +- 3 files changed, 15 insertions(+), 17 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fe9569ab..2844e7f3 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,4 +11,4 @@ # Checklist for code / configuration changes -In [CONTRIBUTING.md] we provide important information for contributing. +See [CONTRIBUTING.md] for all essential information about contributing. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0c7a32c..30efdfc2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,21 +2,19 @@ **Please read the following text before creating a pull request.** -This project is organized and supported by community contributions and maintenance is done in our sparse time. -We welcome any pull request that contributes to the PDFParser (code, documentation, ...). -However, we would point out that you are initially responsible for a contribution. -If you are new to pull requests see [Github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) for further information. +This project is organized and supported by contributions from the community. Maintenance is done in our limited time. +We welcome any pull request that contributes to PDFParser (code, documentation, ...). +However, we would like to point out that you are initially responsible for a contribution. +If you are new to dealing with pull requests, you can find more information at [Github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). Please don't just throw code at us and expect us to handle it. -That being said, we will assist you and give feedback. +Nevertheless, we will support you and give you feedback. -## Important steps +## Important notes -To make life easier for you and us, there is a continuous integration (CI) system that runs software tests and performs a number of other tasks. -The following points describe relevant preparations/inputs for the CI system. -All checks must be green or a pull request is not accepted. - -* If you add/change functionality add at least **one test case** (unit test, system test, ...) to demonstrate that your code is working. There is no need to provide a full fledged PDF file to demonstrate a fix. Instead a unit test may be sufficient sometimes, have a look at [FontTest](https://github.com/smalot/pdfparser/blob/master/tests/PHPUnit/Unit/FontTest.php#L40) for example code. - * :exclamation: **If you dont know how to write a test tell us upfront when opening the pull request and we may add them ourselves or discuss other ways**. This [Medium article](https://pguso.medium.com/a-beginners-guide-to-phpunit-writing-and-running-unit-tests-in-php-d0b23b96749f) might be a good point to start. Code changes without tests are very likely to be rejected. -* Fix reported coding style issues. We use **PHP-CS-Fixer** for that. See https://github.com/smalot/pdfparser/blob/master/.php-cs-fixer.php for more information about our coding styles. See [Developer.md](./doc/Developer.md) for further information. -* In case you **fix an existing issue**, refer to it in the intro text of the pull request. In the following the correct Markdown syntax: `fixes #1234`. This example outlines that you are providing a fix for the issue `#1234`. -* In case **you changed internal behavior/functionality** check our documentation to make sure these changes are **documented properly**: https://github.com/smalot/pdfparser/tree/master/doc +To make life easier for you and us, there is a Continuous Integration (CI) system that carries out software tests and performs a number of other tasks. +The following points describe the relevant preparations/inputs for the CI system. +All checks must be green, otherwise a pull request will not be accepted. +* We only accept code that is bundled with tests, regardless of whether it is a new function or a bug fix. This strengthens the code base and avoids later regressions. :exclamation: **If you don't know how to write a test, tell us upfront when you open the pull request and we might add them ourselves or discuss other ways**. This [Medium article](https://pguso.medium.com/a-beginners-guide-to-phpunit-writing-and-running-unit-tests-in-php-d0b23b96749f) might be a good starting point. Code changes without tests are very likely to be rejected. +* Fix reported issues with the coding style. We use **PHP-CS-Fixer** for this. See [.php-cs-fixer.php](./.php-cs-fixer.php) for more information about our coding styles. [Developer.md](./doc/Developer.md) contains more information about this topic. +* If you are fixing an **existing error**, refer to it in the introduction text of the pull request. For example, if you created a fix for issue `#1234` write the following Markdown: `fixes #1234`. +* In case you have changed **internal behavior/functionality**, check our documentation to make sure these changes are **correctly documented**: https://github.com/smalot/pdfparser/tree/master/doc diff --git a/README.md b/README.md index b4cd2799..febcf303 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ The `smalot/pdfparser` is a standalone PHP package that provides various tools t This library is under **active maintenance**. There is no active development by the author of this library (at the moment), but we welcome any pull request adding/extending functionality! -Consult [CONTRIBUTING.md](./CONTRIBUTING.md) for further information about how to contribute. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for further information about how to contribute. ## Features From 91a4c9a5a0dbef8c3821f138bee73f4eb479d030 Mon Sep 17 00:00:00 2001 From: Konrad Abicht Date: Tue, 5 Nov 2024 09:01:12 +0100 Subject: [PATCH 4/4] CONTRIBUTING.md: small text refinement --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 30efdfc2..92e25243 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,11 +9,10 @@ If you are new to dealing with pull requests, you can find more information at [ Please don't just throw code at us and expect us to handle it. Nevertheless, we will support you and give you feedback. -## Important notes - To make life easier for you and us, there is a Continuous Integration (CI) system that carries out software tests and performs a number of other tasks. The following points describe the relevant preparations/inputs for the CI system. All checks must be green, otherwise a pull request will not be accepted. +* Please create an [issue](https://github.com/smalot/pdfparser/issues) before starting work on any significant changes. * We only accept code that is bundled with tests, regardless of whether it is a new function or a bug fix. This strengthens the code base and avoids later regressions. :exclamation: **If you don't know how to write a test, tell us upfront when you open the pull request and we might add them ourselves or discuss other ways**. This [Medium article](https://pguso.medium.com/a-beginners-guide-to-phpunit-writing-and-running-unit-tests-in-php-d0b23b96749f) might be a good starting point. Code changes without tests are very likely to be rejected. * Fix reported issues with the coding style. We use **PHP-CS-Fixer** for this. See [.php-cs-fixer.php](./.php-cs-fixer.php) for more information about our coding styles. [Developer.md](./doc/Developer.md) contains more information about this topic. * If you are fixing an **existing error**, refer to it in the introduction text of the pull request. For example, if you created a fix for issue `#1234` write the following Markdown: `fixes #1234`.