charcoal/charcoal

The Charcoal Framework monorepo

Maintainers

Details

github.com/charcoalphp/charcoal

Homepage

Source

Issues

Installs: 409

Dependents: 3

Suggesters: 0

Security: 0

Stars: 8

Watchers: 7

Forks: 0

Open Issues: 17

v5.0.0 2024-03-13 15:04 UTC

Requires

Requires (Dev)

Replaces

MIT 44c1e601ea5bce051d4b675563afa5dd68a6c042

  • Locomotive
  • Mathieu Ducharme <mat.woop@locomotive.ca>
  • Chauncey McAskill <chauncey.woop@locomotive.ca>
  • Joel Alphonso <joel.woop@locomotive.ca>
  • Dominic Lord <dom.woop@locomotive.ca>
  • Benjamin Roch <ben.woop@locomotive.ca>

frameworkcmscharcoal

This package is auto-updated.

Last update: 2024-12-16 17:34:19 UTC

README


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.

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.

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

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.