Contributing to Pico
Pico aims to be a high quality Content Management System (CMS) but at the same time wants to give contributors freedom when submitting fixes or improvements.
As such we want to encourage but not obligate you, the contributor, to follow these guidelines. The only exception to this are the guidelines elucidated in the Prevent
Having said that: we really appreciate it when you apply the guidelines in part or wholly as that will save us time which, in turn, we can spend on bugfixes and new features.
If you want to report an issue with Pico's core, please create a new Issue on GitHub. Concerning problems with plugins or themes, please refer to the website of the developer of this plugin or theme.
Please describe your issue as clear as possible and always include the Pico version you're using. Provided that you're using plugins, include a list of them too. We need information about the actual and expected behavior, the steps to reproduce the problem, and what steps you have taken to resolve the problem by yourself (i.e. your own troubleshooting).
Once you decide you want to contribute to Pico's core (which we really appreciate!) you can fork the project from https://github.com/picocms/Pico. If you're interested in developing a plugin or theme for Pico, please refer to the development section of our website.
Please do not develop your contribution on the
master branch of your fork, but create a separate feature branch, that is based off the
master branch, for each feature that you want to contribute.
Not doing so means that if you decide to work on two separate features and place a pull request for one of them, that the changes of the other issue that you are working on is also submitted. Even if it is not completely finished.
Please keep in mind that pull requests should be small (i.e. one feature per request), stick to existing coding conventions and documentation should be updated if required. It's encouraged to make commits of logical units and check for unnecessary whitespace before committing (try
git diff --check). Please reference issue numbers in your commit messages where appropriate.
For historical reasons we don't use formal namespaces. Markdown files in the
content-sample folder (the inline documentation) must follow a hard limit of 80 characters line length.
It is recommended to check your code using PHP_CodeSniffer using Pico's
.phpcs.xml standard. Use the following command:
$ ./vendor/bin/phpcs --standard=.phpcs.xml [file]...
With this command you can specify a file or folder to limit which files it will check or omit that argument altogether, in which case the current working directory is checked.
Keep documentation in sync
Pico accepts the problems of having redundant documentation on different places (concretely Pico's inline user docs, the
README.md and the website) for the sake of a better user experience. When updating the docs, please make sure to keep them in sync.
If you update the
content-sample/index.md, please make sure to update the corresponding files in the
_docs folder of the
picocms.github.io repo (i.e. Pico's website) and vice versa. Unfortunately this involves three (!) different markdown parsers. If you're experiencing problems, use Pico's
erusev/parsedown-extra as a reference. You can try to make the contents compatible to Kramdown (Pico's website) and Redcarpet (
README.md) by yourself, otherwise please address the issues in your pull request message and we'll take care of it.
Pico follows Semantic Versioning 2.0 and uses version numbers like
PATCH. We will increment the:
MAJORversion when we make incompatible API changes,
MINORversion when we add functionality in a backwards-compatible manner, and
PATCHversion when we make backwards-compatible bug fixes.
For more information please refer to the http://semver.org website.
master branch contains the current development version of Pico. It is likely unstable and not ready for production use.
master branch always consists of a deployable (but not necessarily deployed) version of Pico. As soon as development of a new
MINOR release starts, a separate branch (e.g.
pico-1.1) is created and a pull request is opened to receive the desired feedback.
Pico's actual development happens in separate development branches. Development branches are prefixed by:
feature/for bigger features,
enhancement/for smaller improvements, and
bugfix/for non-trivial bug fixes.
As soon as development reaches a point where feedback is appreciated, a pull request is opened. After some time (very soon for bug fixes, and other improvements should have a reasonable feedback phase) the pull request is merged and the development branch will be deleted. Trivial bug fixes which will be part of the next
PATCH version will be merged directly into
Build & Release process
We're using Travis CI to automate the build & release process of Pico. It generates and deploys phpDoc class docs for new releases and on every commit to the
master branch. Travis also prepares new releases by generating Pico's pre-built packages, a version badge and pushing both to our website (the
picocms.github.io repo). Please refer to our
.travis.yml and the
_build directory 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:
Version 1.0.0 * [Security] ... * [New] ... * [Changed] ... * [Fixed] ... * [Removed] ...
Travis CI will draft the new release on GitHub 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 will be updated automatically.