Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
72 lines (56 loc) · 4.47 KB

CONTRIBUTING.md

File metadata and controls

72 lines (56 loc) · 4.47 KB
Raw

Contribution Guidelines

Awesome CakePHP aims to be a concise list of the best plugins, resources and tools the CakePHP ecosystem has to offer. The suggested software should ideally be one of the following:

  • Widely known or recognized within the CakePHP community
  • Established and mature
  • Unique in its approach
  • Fulfill a niche gap in the market

For a plugin to stay on it, it needs to be somewhat actively maintained.

Please ensure your pull request adheres to the following guidelines:

  • Your suggestion will be closed if it has been previously rejected or is a duplicate.
  • Please search previous suggestions before making a new one.
  • Write a meaningful pull request description that includes a link to the project.
  • Code, comments and documentation need to be in English.
  • Libraries that are PHP 8.1+, Composer-installable, CakePHP-PSR compliant, tested and documented are preferred.
  • A license file must be in the root directory (usually named LICENSE).
  • If possible, please publish your library under an open-source license (preferably MIT).
  • Please make an individual pull request for each suggestion.
  • New categories or improvements to the existing categorization are welcome.
  • Keep descriptions short, clear, unbiased, and free of jargon.
  • Adheres to the following Markdown format: [Plugin Name](LINK) - DESCRIPTION.
  • End all descriptions with a full stop/period and no trailing whitespace.
  • Check your spelling and grammar.
  • Proposed libraries should ideally have 10+ stars.
  • Please keep the lists in alphabetical order.
  • Name plugins as ExactPluginName plugin. The name is the CamelCase namespace and ideally matches the composer package name (minus the dashed casing).

Please make sure your suggestion meets all the criteria before submitting a pull request, or it may be closed without review.

Maintainer Discretion: Maintainers reserve the right to decline any contribution or remove existing entries at any time. Common reasons include projects becoming unmaintained, outdated, superseded by better alternatives, or no longer meeting quality standards.

Thank you for your suggestions!

Tips for creating composer packages

Choose a semantically meaningful name for the package name. This should ideally be prefixed with the dependency, in this case "cakephp" as the framework. The vendor name will usually be your GitHub username. Do not use the CakePHP namespace (cakephp) as this is reserved to CakePHP owned plugins. The convention is to use lowercase letters and dashes as separators.

So if you created a plugin Logging with your GitHub account FooBar, a good name would be foo-bar/cakephp-logging. And the CakePHP owned "Localized" plugin can be found under cakephp/localized respectively.

You can prefix your namespace and therefore your plugin name with your vendor name to make sure there are no collisions with other similar plugins. This would then be in your composer autoload definition:

"MyName\\MyPlugin\\": "src/"

The name then would be MyName/MyPlugin and the composer package name then would be inflected as my-name/my-plugin. GitHub URL would be then github.com/my-name/my-plugin respectively.

Make sure those names match to avoid confusion here for users.

Additional naming tips:

  • Do not include the CakePHP major version number here or for the composer package name or description. The README can state the version per branch instead or link to the wiki which then can do this across all branches in a less cumbersome way.

Tips for creating CakePHP plugins

  • Follow https://github.com/php-pds/skeleton
  • Make sure the README or docs contain installation and usage instructions. The more verbose, the better.
  • The composer.json contains necessary dependencies including constraints (ideally using semver and ^ operator).
  • PHP constraint is set as >=, e.g. >=7.4 (with the minimum being the current one of the corresponding CakePHP minor) and allows also latest new PHP minors to work.
  • Make sure to set the type to "cakephp-plugin", not "library" ("type": "cakephp-plugin")
  • The plugin contains basic tests (unit, ...) of the functionality provided.
  • It should have Travis or some CI set up. Make sure to set min/max of PHP as matrix elements.
  • You can add badges under the README h1 header to visually show your tests are green etc.
  • Ideally, also check PHPStan on src/ dir and prefer-lowest to ensure a high quality for your plugin.