|Classes of Caleb||>||PHP Common Class Library||>||CONTRIBUTING.md||>||Download|
Want to help?
If you want to report bugs, suggest new features, new classes, etc, you should start at the issues page. Any already reported bugs, requested features, classes, progress checklists, discussions, etc should available there, and everyone is welcome to participate and contribute. If you have something to add, whether for an existing issue or a new issue, feel free to do so.
The project is open-source, released by its author under the GNU/GPLv2 license, so if you want fork/copy the project and to make your own modifications, you're welcome to do so. If you feel that your modifications could be beneficial to the project and its community, consider sending a pull request (include a description with pull requests, so that we know what we're looking at) so that we can review your modifications and consider integrating them as part of the project.
Anyone interested in contributing to the project is encouraged to do so.
Not sure how to help? Here are some things you could do.
The common classes package code style guidelines.
From here onward in this document, the words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted in accordance with RFC 2119.
The common classes package adopts and adheres to PSR-1: Basic Coding Standard, PSR-2: Coding Style Guide, and PSR-4: Autoloader (as closely as possible, and to the best of our abilities). Whenever possible, any and all future contributions to the codebase SHOULD adopt and adhere to these standards, too. If you're unfamiliar with these, I would recommend reading them carefully.
The common classes package adopts PHPDoc to annotate and describe PHP code. If you're unfamiliar with this, I would recommend reading the linked documentation carefully.
To avoid unnecessary complexity, red tape, or hindrances to future contributions, future contributions will be measured against any other PSRs or style guides not yet mentioned, IF and WHEN it becomes relevant and useful to do so (i.e., we'll cross those bridges when we get to them). To be more concise and to avoid unnecessary duplication in this document, any points already covered, either by this document, or by any linked documents (e.g., the PSRs adopted by this project), won't be repeated.
All project files (including all code, markup, etc) MUST utilise UTF-8 encoding (without BOM), and MUST NOT contain any trailing whitespace.
When writing code or markup, contributors SHOULD aim for maximum readability, and maximum maintainability for their contributions.
All PHP functions, methods, and closures MUST be properly and accurately annotated by an attached DocBlock. All PHP files MUST contain a DocBlock header, to describe the general nature of the file. All attached DocBlocks SHOULD be concise, and SHOULD NOT be overly verbose (i.e., containing more than necessary). All comments in all PHP files and code MUST conform to PHPDoc (i.e., as DocComments). Where the purpose and intent of some particular code is highly obtuse, unclear, or not easily understood, it SHOULD be commented. Where the purpose and intent of some particular code is highly transparent and easily stood (and where not otherwise already dictated by this document), it SHOULD NOT be commented. All annotation, and all comments, MUST be written in English.
The common classes package version release guidelines.
The common classes package adopts and adheres to SemVer (Semantic Versioning). If you're unfamiliar with this, I would recommend reading the linked documentation carefully.
Extending upon the rules provided by SemVer, the following are to be interpreted as backwards-incompatible changes: - Anything that increases the minimum PHP version requirement. - The permanent removal of any specific class. - Any backwards-incompatible changes to the overall way that a class is intended to be used.
When tagging a new release, the "tag version" MUST be formatted as "vM.m.p" (where, per SemVer definitions, "M" is the MAJOR version number, "m" is the MINOR version number, and "p" is the PATCH version number), and the "release title" MUST be formatted as "Common Classes Package vM.m.p". The release description SHOULD contain all relevant changes implemented since the previous most recent release targeted to the same branch. The release description SHOULD NOT contain anything irrelevant to the release.
The common classes package documentation guidelines.
All formal documentation for the common classes package can be found in the
When sending pull requests, which branch should I target?
Branches are named according to major version. Therefore, if you want to affect something in v1, target the v1 branch; if you want to affect something in v2, target the v2 branch; and so on. If a branch exists for a specific feature, a specific planned task, or similar, and that's the thing that you're working on, target that branch instead. If no branch exists for the particular major version you're wanting to affect, or if you feel that you need to be able to target your pull request somewhere else, you can ask for a new branch to be created. Target master only if no other alternatives are available.
Last Updated: 9 May 2019 (2019.05.09).