beenull/Pico
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Update CONTRIBUTING.md to include latest changes

Browse source
This commit is contained in:
Daniel Rudolf 2022-03-12 18:02:11 +01:00
parent c0639ccef6
commit 81c21722d3
No known key found for this signature in database
GPG key ID: A061F02CD8DE4538
1 changed files with 19 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
CONTRIBUTING.md
View file

@ -92,7 +92,7 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE. OTHER DEALINGS IN THE SOFTWARE.
``` ```
Please note that developing a *plugin* or *theme* for Pico is *not* assumed to be a contribution to Pico itself. By developing a plugin or theme you rather create a 3rd-party project that just uses Pico. Following the spirit of open source, we want to *encourage* you to release your plugin or theme under the terms of a [OSI-approved open source license](https://opensource.org/licenses). After all, Pico is open source, too! Please note that developing a *plugin* or *theme* for Pico is *not* assumed to be a contribution to Pico itself. By developing a plugin or theme you rather create a 3rd-party project that just uses Pico. Following the spirit of open source, we want to *encourage* you to release your plugin or theme under the terms of an [OSI-approved open source license](https://opensource.org/licenses). After all, Pico is open source, too!
### Prevent `merge-hell` ### Prevent `merge-hell`
@ -153,9 +153,13 @@ As soon as development reaches a point where feedback is appreciated, a pull req
Build & Release process Build & Release process
----------------------- -----------------------
We use [GitHub Actions](https://github.com/picocms/Pico/actions) to automate the build & release process of Pico - also called [continous integration](https://en.wikipedia.org/wiki/Continuous_integration), or CI. With our CI pipeline we generate and deploy a [PHP class documentation](https://picocms.org/phpDoc/) (powered by [phpDoc](https://phpdoc.org)) for new releases and on every commit to the `master` branch. Our CI pipeline also prepares new releases by generating Pico's pre-built release packages, a version badge, code statistics (powered by [cloc](https://github.com/AlDanial/cloc)) and updates our website (the [`picocms.github.io` repo](https://github.com/picocms/picocms.github.io)). Please refer to the [`deploy-branch.yml` workflow](https://github.com/picocms/Pico/blob/master/.github/workflows/deploy-branch.yml), the [`deploy-release.yml` workflow](https://github.com/picocms/Pico/blob/master/.github/workflows/deploy-release.yml), the [`picocms/ci-tools` repo](https://github.com/picocms/ci-tools) and Pico's [`.build/build.sh` script](https://github.com/picocms/Pico/blob/master/.build/build.sh) for details. We use [GitHub Actions](https://github.com/picocms/Pico/actions) to automate the test, build & release process of Pico - also called [continous integration](https://en.wikipedia.org/wiki/Continuous_integration), or CI. With our CI pipeline we perform various tests on every push, including code style checks (powered by [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)). Due to historical reasons we don't have any unit or integration tests, so you must manually test your changes. Pull requests adding unit or integration tests are very welcome though! Please refer to the [`test.yml` workflow](https://github.com/picocms/Pico/blob/master/.github/workflows/test.yml) for details.
As insinuated above, it is important that each commit to `master` is deployable. Once development of a new Pico release is finished, trigger Pico's build & release process by pushing a new Git tag. This tag should reference a (usually empty) commit on `master`, which message should adhere to the following template: With our CI pipeline we furthermore generate and deploy a [PHP class documentation](https://picocms.org/phpDoc/) (powered by [phpDoc](https://phpdoc.org)) for new releases and on every push to the `master` branch. Our CI pipeline also prepares new releases by generating a version badge, code statistics (powered by [cloc](https://github.com/AlDanial/cloc)) and updates our website (the [`picocms.github.io` repo](https://github.com/picocms/picocms.github.io)). Please refer to the [`deploy-branch.yml`](https://github.com/picocms/Pico/blob/master/.github/workflows/deploy-branch.yml) and [`deploy-release.yml`](https://github.com/picocms/Pico/blob/master/.github/workflows/deploy-release.yml) workflows for details, as well as the [`picocms/ci-tools` repo](https://github.com/picocms/ci-tools).
To build a release package or publish a new release, use Pico's [Makefile](https://github.com/picocms/Pico/blob/master/Makefile) (see [Wikipedia](https://en.wikipedia.org/wiki/Make_(software)) for details), which is more or less a wrapper for Pico's [`.build/build.sh` script](https://github.com/picocms/Pico/blob/master/.build/build.sh). You can build both development versions (like `v1.0.0-dev`) and "actual" releases (both stable and pre-releases, like `v1.0.0` or `v1.0.0-beta.1`). The `build` target builds a development version by default; to build a release, pass the `version` argument (e.g. `make build version=v1.0.0`). Please note that the build script will perform a sophisticated list of sanity checks before actually building a non-development version of Pico (e.g. your Git working tree must be clean, and the Git tag matching the version to build must be checked out). To publish a new release, run the `publish` target. It will build the release packages and push them to GitHub, creating a new release there and triggering the previously mentioned workflow for new releases. You must then manually add the changelog to the release description.
As insinuated above, it is important that each commit to `master` is deployable. Once development of a new Pico release is finished, publish the new release using `make publish version=v1.0.0`. The matching Git tag should reference a (usually empty) commit on `master`, whose message should adhere to the following template:
``` ```
Version 1.0.0 Version 1.0.0
@ -171,39 +175,39 @@ Before pushing a new Git tag, make sure to update the `Pico::VERSION` and `Pico:
If you're pushing a new major or minor release of Pico, you should also update Pico's `composer.json` to require the latest minor releases of Pico's dependencies. Besides, don't forget to update the `@version` tags in the PHP class docs. If you're pushing a new major or minor release of Pico, you should also update Pico's `composer.json` to require the latest minor releases of Pico's dependencies. Besides, don't forget to update the `@version` tags in the PHP class docs.
Our CI pipeline will draft the new [release on GitHub](https://github.com/picocms/Pico/releases) automatically, but will require you to manually amend the descriptions formatting. The latest Pico version is always available at https://github.com/picocms/Pico/releases/latest, so please make sure to publish this URL rather than version-specific URLs. [Packagist](https://packagist.org/packages/picocms/pico) will be updated automatically. The latest Pico version is always available at https://github.com/picocms/Pico/releases/latest, so please make sure to reference this URL rather than version-specific URLs. [Packagist](https://packagist.org/packages/picocms/pico) will be updated automatically.
Labeling of Issues & Pull Requests Labeling of Issues & Pull Requests
---------------------------------- ----------------------------------
Pico makes use of GitHub's label and milestone features, to aide developers in quickly identifying and prioritizing which issues need to be worked on. The starting point for labeling issues and pull requests is the `type` label, which is explained in greater detail below. The `type` label might get combined with a `pri` label, describing the issue's priority, and a `status` label, describing the current status of the issue. Pico makes use of GitHub's label and milestone features, to aid developers in quickly identifying and prioritizing which issues need to be worked on. The starting point for labeling issues and pull requests is the `type` label, which is explained in greater detail below. The `type` label might get combined with a `pri` label, describing the issue's priority, and a `status` label, describing the current status of the issue.
Issues and pull requests labeled with `info: Feedback Needed` indicate that feedback from others is highly appreciated. We always appreciate feedback at any time and from anyone, but when this label is present, we explicitly *ask* you to give feedback. It would be great if you leave a comment! Issues and pull requests labeled with `info: Feedback Needed` indicate that feedback from others is highly appreciated. We always appreciate feedback at any time and from anyone, but when this label is present, we explicitly *ask* you to give feedback. It would be great if you leave a comment!
- The `type: Bug` label is assigned to issues or pull requests, which have been identified as bugs or security issues in Pico's core. It might get combined with the `pri: High` label, when the problem was identified as security issue, or as a so-called "show stopper" bug. In contrast, uncritical problems might get labeled with `pri: Low`. `type: Bug` issues and pull requests are usually labeled with one of the following `status` labels when being closed: - The `type: Bug` label is assigned to issues or pull requests, which have been identified as bugs or security issues in Pico's core. It might get combined with the `pri: High` label, when the problem was identified as security issue, or as a so-called "show stopper" bug. In contrast, uncritical problems might get labeled with `pri: Low`. If a pull request isn't mergeable at the moment, it is labeled with `status: Work In Progress` until development of the pull request is finished. `type: Bug` issues and pull requests are usually labeled with one of the following `status` labels when being closed:
- `status: Resolved` is used when the issue has been resolved. - `status: Resolved` is used when the issue has been resolved (used with issues only).
- `status: Conflict` indicates a conflict with another issue or behavior of Pico, making it impossible to resolve the problem at the moment. - `status: Conflict` indicates a conflict with another issue or behavior of Pico, making it impossible to resolve the problem at the moment.
- `status: Won't Fix` means, that there is indeed a problem, but for some reason we made the decision that resolving it isn't reasonable, making it intended behavior. - `status: Won't Fix` means, that there is indeed a problem, but for some reason we made the decision that resolving it isn't reasonable, making it intended behavior.
- `status: Rejected` is used when the issue was rejected for another reason. - `status: Rejected` is used when the issue was rejected for another reason.
- The `type: Enhancement` and `type: Feature` labels are used to tag pull requests, which introduce either a comparatively small enhancement, or a "big" new feature. As with the `type: Bug` label, they might get combined with the `pri: High` or `pri: Low` labels to indicate the pull request's priority. If a pull request isn't mergeable at the moment, it is labeled with `status: Work In Progress` until development of the pull request is finished. After merging or closing the pull request, it is labeled with one of the `status` labels as described above for the `type: Bug` label. - The `type: Enhancement` and `type: Feature` labels are used to tag pull requests, which introduce either a comparatively small enhancement, or a "big" new feature. As with the `type: Bug` label, they might get combined with the `pri: High` or `pri: Low` labels to indicate the pull request's priority. They might also be labeled with `status: Work In Progress`. After merging or closing the pull request, it is labeled with one of the `status` labels as described above for the `type: Bug` label.
- The `type: Idea` label is similar to the `type: Enhancement` and `type: Feature` labels, but is used for issues or incomplete and abandoned pull requests. It is otherwise used in the exact same way as `type: Enhancement` and `type: Feature`. - The `type: Idea` label is similar to the `type: Enhancement` and `type: Feature` labels, but is used for issues, or incomplete and abandoned pull requests. It is otherwise used in the exact same way as `type: Enhancement` and `type: Feature`.
- The `type: Release` label is used in the exact same way as `type: Feature` and indicates the primary pull request of a new Pico release (please refer to the *Branching* and *Build & Release process* sections above). - The `type: Release` label is used in the exact same way as `type: Feature` and indicates the primary pull request of a new Pico release (please refer to the *Branching* and *Build & Release process* sections above).
- The `type: Notice`, `type: Support` and `type: Discussion` labels are used to indicate "fyi" issues, support-related issues (e.g. issues opened by users or developers asking questions), and issues with disucssions about arbitrary topics related to Pico. They are neither combined with `pri` labels, nor with `status` labels. - The `type: Notice`, `type: Support` and `type: Discussion` labels are used to indicate "fyi" issues, support-related issues (e.g. issues opened by users or developers asking questions), and issues with discussions about arbitrary topics related to Pico. They are neither combined with `pri` labels, nor with `status` labels.
- The `type: Duplicate` label is used when there is already another issue or pull request related to this problem or feature request. Issues labeled with `type: Duplicate` are immediately closed. - The `type: Duplicate` label is used when there is already another issue or pull request related to this problem or feature request. Issues labeled with `type: Duplicate` are immediately closed.
- The `type: Invalid` label is used for everything else, e.g. issues or pull requests not related to Pico, or invalid bug reports. This includes supposed bug reports that concern actually intended behavior. - The `type: Invalid` label is used for everything else, e.g. issues or pull requests not related to Pico, or invalid bug reports. This includes supposed bug reports that concern actually intended behavior, unless the report isn't rather considered a support request (also see `type: Support`).
The `status: Deferred` label might get added to any open issue or pull request to indicate that it is still unresolved and will be resolved later. This is also true for the `info: Pinned` label: It indicates a important issue or pull request that remains open on purpose. The `status: Deferred` label might get added to any open issue or pull request to indicate that it is still unresolved and will be resolved later. This is also true for the `info: Pinned` label: It indicates an important issue or pull request that remains open on purpose.
After resolving a issue, we usually keep it open for about a week to give users some more time for feedback and further questions. This is especially true for issues with the `type: Notice`, `type: Support`, `type: Discussion` and `type: Invalid` labels. After 7 days with no interaction, the [GitHub Actions](https://github.com/picocms/Pico/actions/workflows/stale.yml) bot adds the `info: Stale` label to the issue to ask the participants whether the issue has been resolved. If no more activity occurs, the issue will be automatically closed by Stale bot 2 days later. After resolving an issue, we usually keep it open for about a week to give users some more time for feedback and further questions. This is especially true for issues with the `type: Notice`, `type: Support`, `type: Discussion` and `type: Invalid` labels. After 7 days with no interaction, the [GitHub Actions](https://github.com/picocms/Pico/actions/workflows/stale.yml) bot adds the `info: Stale` label to the issue to ask the participants whether the issue has been resolved. If no more activity occurs, the issue will be automatically closed by Stale bot 2 days later.
Issues and pull requests labeled with `info: Information Needed` indicate that we have asked one of the participants for further information and didn't receive any feedback yet. It is usually added after Stale bot adds the `info: Stale` label to give the participants some more days to give the necessary information. Issues and pull requests labeled with `info: Information Needed` indicate that we have asked one of the participants for further information and didn't receive any feedback yet. It is usually added after Stale bot adds the `info: Stale` label to give the participants some more days to provide the necessary information, unless it is automatically closed due to inactivity.
Issues and pull requests, which are rather related to upstream projects (i.e. projects Pico depends on, like Twig), are additionally labeled with `info: Upstream`. Issues and pull requests, which are rather related to upstream projects (i.e. projects Pico depends on, like Twig), are additionally labeled with `info: Upstream`.
When a issue or pull request isn't directly related to Pico's core, but the project as a whole, it is labeled with `info: Meta`. Issues labeled with `info: Website` are related to [Pico's website](https://picocms.org), however, in this case it is usually expedient to move the issue to the [`picocms.github.io` repo](https://github.com/picocms/picocms.github.io) instead. The same applies to the `info: Pico CMS for Nextcloud` label; these issues are related to [Pico CMS for Nextcloud](https://apps.nextcloud.com/apps/cms_pico). If an issue or pull request isn't directly related to Pico's core, but the project as a whole, it is labeled with `info: Meta`. Issues labeled with `info: Website` are related to [Pico's website](https://picocms.org), however, in this case it is usually expedient to move the issue to the [`picocms.github.io` repo](https://github.com/picocms/picocms.github.io) instead. The same applies to the `info: Pico CMS for Nextcloud` label; these issues are related to [Pico CMS for Nextcloud](https://apps.nextcloud.com/apps/cms_pico).