Skip to content

Latest commit

 

History

History
402 lines (293 loc) · 20.4 KB

README.md

File metadata and controls

402 lines (293 loc) · 20.4 KB
Raw

Charcoal
by Locomotive 🚂

License Latest Stable Version Uses Semantic Release with Conventional Commits Commitizen-friendly Supported PHP Version

Charcoal is a web framework and content management system that adapts to all of your project's needs.

This repository is a monorepo containing the entirety of the web framework. Charcoal can be used as a full stack framework or as standalone packages which can be used independently.

Charcoal packages

Core packages can be found in the packages directory.

Directory Distribution Description
admin charcoal/admin The administration dashboard for Charcoal.
app charcoal/app The web application layer (container, routing, controllers,…), based on Slim.
attachment charcoal/attachment Provides support for working with relationships between models.
cache charcoal/cache The cache layer, based on Stash.
cms charcoal/cms Provides content management system (CMS) tools and extensions.
config charcoal/config The base configuration and entity layer most packages build upon.
core charcoal/core The model, repository, and database layer.
email charcoal/email Provides support for sending emails, based on PHPMailer.
factory charcoal/factory Provides support for object creation (factory, builder, class resolution,…).
image charcoal/image Provides support for image handling and manipulation.
object charcoal/object Provides support for advanced modeling (routable, revisionable, authoriship,…).
property charcoal/property The model metadata layer.
queue charcoal/queue Provides support for building queues.
translator charcoal/translator Provides support for internationalization, based on Symfony.
ui charcoal/ui Provides layout tools (dashboards, layouts, forms, menus,…).
user charcoal/user The user modeling, authentication, and authorization layer.
view charcoal/view The view layer with support for Mustache, Twig,…

Installation

The preferred (and only supported) method is with Composer:

composer require charcoal/charcoal

To start from a working skeleton:

composer create-project charcoal/boilerplate

Standalone packages

The Charcoal framework is split into standalone packages which can be used independently. For example, a project might not need an administration panel, a queue system, or to send emails.

composer require charcoal/app charcoal/api custom/admin

Migrate a project to charcoal/charcoal

The following will aide with converting a project from locomotivemtl/charcoal-* to charcoal/*.

ℹ️ Previously all core packages maintained their own version numbering independently.

The monorepo framework uses a shared version number for all core packages for consistent and expected interoperability.

ℹ️ The contrib packages continue to maintain their existing independent version numbering.

Option A — If you want to replace all packages with the full-stack framework package:

  1. Remove requirements for core packages (locomotivemtl/charcoal-*) in your composer.json file.

  2. Replace requirements for contrib packages (locomotivemtl/charcoal-contrib-*), in your composer.json file, with equivalents from charcoal/contrib-*.

  3. Run composer require charcoal/charcoal to install the framework.

  4. Run composer update to ensure all requirements are up-to-date.

  5. Run the following migration script:

    ./vendor/charcoal/charcoal/build/script/migrate-project

    The migrate-project script will update all metadata paths in your project's configuration files. Afterwards, it will edit or create a .env environment variable file with the key PACKAGES_PATH set to: vendor/charcoal/charcoal/packages.

    This allows the %packages.path% string template to expand to the packages location within charcoal/charcoal, otherwise it will lead in the vendor directory.

Option B — If you want to replace all packages with new standalone packages:
  1. Replace requirements for core packages (locomotivemtl/charcoal-*), in your composer.json file.
  2. Replace requirements for contrib packages (locomotivemtl/charcoal-contrib-*), in your composer.json file, with equivalents from charcoal/contrib-*.
  3. Run composer require charcoal/config charcoal/core… to install the packages.
  4. Run composer update to ensure all requirements are up-to-date.
  5. Replace occurrences of vendor/locomotivemtl/charcoal-* in your configuration files with vendor/charcoal/*.

Dependencies

⚠️ Required

  • PHP 7.4 or 8.0

⚙️ Configuration

[TODO]

Usage

[TODO]

Development

Development is made in a seperate branch from the main branch.

⚠️ The main branch is protected and doesn't allow pushing changes directly into.

To install the development environment:

composer install

To run the scripts (phplint, phpcs, and phpunit):

composer test

Commit message format

Charcoal uses semantic-release to handle the release process.

It uses the commit messages to determine the consumer impact of changes in the codebase. Following formalized conventions for commit messages, semantic-release automatically determines the next Semantic Version number, generates a changelog, and publishes the release.

The current setup uses the Conventional Commits for commit messages. You can consult it for further information.

This repository is Commitizen friendly and is configured to use the Conventional Commits standard, therfore you can install it globally to ease the process of writting commits.

Alternatively, there is some code editor plugins that can help with the creation of conventional commits:

Here is an example of release types based on some commit messages:

  • Patch (Fix) release:

    fix(pencil): stop graphite breaking when too much pressure applied

  • Minor (Feature) release:

    feat(pencil): add 'graphiteWidth' option

  • Major (Breaking) release:

    perf(pencil): remove graphiteWidth option

BREAKING CHANGE: The graphiteWidth option has been removed.
The default graphite width of 10mm is always used for performance reasons.

    ✍🏻 Note that the BREAKING CHANGE: token must be in the foot of the commit.

Development guidelines

Development should be branch-based and commit messages should following Conventional Commits.

Steps Notes
1. Branch from main or checkout develop Make sure the develop branch is up to date with main. You should favor a new branch if the needed work time is not short. On a personal branch, favor using the rebase method to keep up to date with the main branch
2. Do your thing Write some code
3. Commit your changes using the Conventional Commits standard You can use Commitizen or a code editor plugin to help with this process. See the Commit message format section for more information.
4. Push to a remote branch and run the ./create-pr script. Using the ./create-pr to script to create a PR is not mandatory. You could always create it manually, but the script will be faster, generates a changelog message and assigns a reviewer from the @charcoalphp/reviewers
5. Wait for a review and a merge to happen Drink ☕️ and eat 🍕
6. After the merge is done, github workflows will handle the release process, tagging, updating dependencies and updatting the changelog. Good Job ! 🤘

Maintenance and automations

Symplify's MonorepoBuilder is used to handle the conformity between the core repo and it's packages. It will sync composer.json files and packages versions.

[TODO] Semantic release config in .releaserc

[TODO] Conventional Commits

[TODO] Commitizen

Development Dependencies

Development History

This monorepo was created with a many to mono aproach using this guide and tool:

Github Actions

Actions Trigger Description
Release Push on supported branches Trigger a Github release using semantic-release
Split Monorepo Release on main The split action splits the packages into individual repositories. Only triggered when a tag is pushed. Based on symplify/monorepo-split-github-action
Update Changelog Release on main Uses changelog-updater-action to update the changelog of the main branch

Scripts

create-pr

This script streamlines the process of creating a Pull Request. When your branch is ready to be pulled into the main or another [target] branch, this tool will generate it for you, request review form @charcoalphp/reviewers and add a beautiful and readable release note generated from the differences between the two breanches.

Documentation

Description
  Create a pull request on the github repository on the requested branch.
  Default branch: main

Usage
  ./create-pr

Options
  -b, --base          The base branch to merge into for the pull request. [Default: main]
  -h, --head          The branch to compare against the base branch. [Default: The current branch]

Example

# target: the target branch for the pull request. Defaults to [main]
./create-pr -b main -h user:feat-branch

create-release-notes (optional tool)

This script generates release notes on request, returning a changelog based on the requested range of commits or branches.

Documentation:

./build/script/create-release-notes --help

Example:

./build/script/create-release-notes -g --from main

Output:

Changes:

Features

  • create-pr: add a script to trigger a pull request on the remote (3016115)

Bug Fixes

  • create-pr: remove Personal access token from script and replace with $GITHUB_TOKEN instead (f2aaac6)
  • package: add missing semantic-release plugin (59bd1b1)

Contributing

Everyone interacting with Charcoal is expected to follow the code of conduct.

Please see our contribution guide on how to contribute to Charcoal.

If you are tying to report a possible security vulnerability in Charcoal, please see our security policy for more information.

✍🏻 Authors

🎉 Contributors

List of contributors

Made with contrib.rocks.

Changelog

View CHANGELOG.

The changelog is compliant with Keep a Changelog and is autogenerated from autoreleases.

License

Charcoal is licensed under the MIT license. See LICENSE for details.