CakeDC Plugin Standard revision 2

The CakeDC Plugin Standard (revision 2) is a blueprint design and guideline for creating coherent and maintainable plugins for the CakePHP framework.

The standard itself covers the following areas:

  • Development: Contribution to plugins should be normalized, both at the process level as well as for integration.
  • Versioning: Versions need to specify their version state, as well as their target framework code base.
  • Contributing: Clarifying contribution guidelines is key to allowing developers to self organize.
  • Documentation: Documentation for plugins should be consistent in it's structure and content, so the necessary information is available and the format is common for easy consumption.
  • Roadmap: Laying out the direction is important for other developers to align themselves with the proposed objectives.
  • Changelogs: Keeping a clear track of changes made helps everyone know what was fixed, added or removed, and when.
  • Licensing: Although not a confusing topic, it's important you make the right choices about how people use your code before they actually do.

While this is defined as a standard, it's only proposed as a guideline for those who wish to adopt this design. The intention is to set a base from which everyone can build upon.

Development

As plugins are used in live applications its important to focus the development of the code base towards quality and accountability. Only then will the process of developing and maintaining the plugin promote confidence and stability.

Branches

There is no master or main branch in the repository. Instead, well create specific branches following the major version of the plugin, starting with branch X.next-cakeY.

Branch names will follow the the structure X.next-cakeY for example 1.next-cake4. The idea behind this naming scheme is to be clear about the current version of the plugin being maintained, and the target CakePHP version.

$ git branch -a
* 1.next-cake4
remotes/origin/1.next-cake4

This allows the plugin to support features sets which may vary from later versions of the framework.

Only the major versions of the framework are contemplated as version jumps.

When a new version of the framework is released, a new version of the plugin is created to ensure the upgrade steps are applied correctly, deprecations removed etc. Update the default branch in github to point to the latest stable release of the plugin.

IMPORTANT: When using the plugin in your application, always clone a tag for a specific release, and not the master or develop branches directly.

Features

All new features or modifications to base functionality occur as feature branches from X.next-cakeY on a forked repository. To create a feature branch, name your new branch with the format "feature/", followed by a dash ("-") separated description of your change, for example:

$ git checkout -b feature/changing-something 1.next-cake4

These branches are created and then merged as pull requests to the related branch of the main plugin repository.

No feature branches should be created on the main plugin repository (if you have direct access), favoring instead to always fork the repository first, and then create features there.

Issues

Bug fixes or any resolution of broken functionality occur as issue branches from X.next-cakeY on a forked repository. To create an issue branch, name your new branch with the format "issue/", followed by a dash ("-") separated description of your patch, for example:

$ git checkout -b issue/fixing-something 2.next-cake3

Also, if you're basing your changes on an issue which is currently open, reference the issue number at the beginning of your description, for example:

$ git checkout -b issue/1234-fixing-that-thing 2.next-cake3

These branches are created and then merged as pull requests to the related branch of the main plugin repository.

No issue branches should be created on the main plugin repository (if you have direct access), favoring instead to always fork the repository first, and then create issues there.

Versioning

Every time a new release of the plugin occurs a tag is created with its corresponding version. The format of these versions is the major and minor version of the plugin. For example, the tag for version 1.2.0 of the plugin, aimed at version 4 of the framework, would be named 1.2.0 and would be created from branch 1.next-cake4.

$ git checkout 1.next-cake4
$ git tag 1.2.0
$ git push origin --tags

New features are generally not considered for previous versions of the framework, and are only merged to previous versions if they are fully backwards compatible. However, all versions should be updated with security patches.

Note specific restrictions will be added to composer.json file, so plugins versions could not be consecutive. It's perfectly valid to have versions 2.next-cake4 then 3.next-cake3 then 4.next-cake4.

Contributing

In order to contribute new features, enhancements or bug fixes to a plugin simply follow these steps:

There might be some discussion regarding your contribution to the repository before any code is merged in, so be prepared to provide feedback on your contribution if required.

Documentation

Code is awesome, but without a firm understand of how to implement a plugin developers can sometimes waste valuable time trying to work out the intended usage. The following define some ways to help people help themselves.

Readme

The README is possibly the most important part of the documentation, as it's usually the first point of reference. Therefore, it's important that from this location developers can find everything they need be related to the plugin. Create a file README.md at the root of the plugin, markdown syntax is recommended.

The README is typically separated into various sections, in a common order:

  • Description: A description of the plugin and an overview of it's features
  • Requirements: Any requirements for the plugin, including PHP and CakePHP versions, as well as any third party dependencies.
  • Setup: A quick reference to download and setup the plugin in your project.
  • Documentation: The documentation for the plugin, or instructions on where to find support material, roadmaps, API docs, etc.
  • Support: How people should request for support, and the preferred channels provisioned by the maintainers.
  • Contributing: Specific details on how to contribute to the code, and any strategy used for integration.
  • License: The license information for your plugin, as well as any specific copyright information.

Changelog

Create a CHANGELOG.md and follow standards defined in https://keepachangelog.com/en/1.0.0/.

Remember to update the changelog before tagging a new version, including the relevant changes. Write the changelog for humans, specifically for your "future" yourself, he will be grateful.

To review all commits related to your release you can use the following command:

$ git log 1.1.6..HEAD --no-merges --oneline

Docs

If you have a large amount of documentation it can help to organize it as separate files. To do so, create a directory named "Docs" in the root of your plugin repository, then add a file named "Home.md". If you don't want to use markdown for your syntax then simply change the extension to your preferred format, for example:

/Docs/Home.md

Now, in your "Home.md" file, add an index to the sections which form part of your documentation. Here are a few sections you could consider including:

  • Overview: A detailed description of the plugin and the functionality it provides.
  • Installation: Step by step instructions for installing the plugin and any dependencies it may require (check out Composer to improve this process).
  • Configuration: A list of the configuration options available and their usage.
  • Getting Started: An introduction to using the plugin's features and integrating it into your application's code base.
  • Examples: A snippet of code is worth a thousand words, so try and provide as many use cases as possible.
  • Tutorials: Any topics which may require additional explanation, as well as key topics, such as an initial Hello World.
  • If needed, you may want to create a number of files under a common section, for example, "Tutorials". When doing so, create the section with a file of the same name, which serves as an index for the linked files.
/Docs/Tutorials.md

Then, simply create the files under a directory with the section's name.

/Docs/Tutorials/Hello-World.md

The files themselves can then be linked using a relative path, for example:

[Hello World](Tutorials/Hello-World.md)

File names should match the title of the topic, using dashes ("-") between words, so directory listing allows for easy discovery.

Although the technical documentation is accessible from the doc blocks in the code itself it can be useful to host the documentation for the API, using a tool such as http://www.apigen.org for example, similar to the API for CakePHP itself at http://api.cakephp.org.

Roadmap

For both community involvement and clarity as to the direction of development it's important to maintain a roadmap, which outlines the pending features and desired improvements. If your roadmap is organized into milestones you can easily define your objectives for each iteration, which then allows people to get involved inline with your schedule.

We recommend creating issues and milestones to track the roadmap of your plugin:

If your code repository does not provide these features, you can fallback to a markdown file ROADMAP.md where you describe the future milestones and items to do.

Licensing

Choosing the right license to release your code under is an important decision that shouldn't be overlooked. The CakePHP framework (http://www.cakephp.org), for example, is released under the MIT (https://opensource.org/licenses/MIT) license. However, there are many licenses, each with their own specific approach.

Before releasing your plugin, if you're not sure how other people should use your code, take some time to review the licenses available. If you find another license which isn't listed, but are still interested in your code being Open Source, then be sure to check for its compliance with the OSR (https://opensource.org/osr-compliance).

There's also the option of dual or multi-licensing. This allows for proprietary derivative works to possibly pay a license fee to use the code, while the plugin remains free for Open Source projects. This can be especially useful if you require funding for the further development of your code, or to cover costs related to the development.

In case of doubt, if you're working on an Open Source plugin, just pick https://opensource.org/licenses/MIT.

Document history:

  • Revision 2: 2020-12-17

NEED A CUSTOM SOLUTION?
GET IN TOUCH:

We Bake with CakePHP