by Locomotive 🚂

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.

Core packages can be found in the packages directory.

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

composer require charcoal/charcoal

To start from a working skeleton:

composer create-project charcoal/boilerplate

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 

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.

• PHP 7.4 or 8.0

[TODO]

[TODO]

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

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:

• vscode
  • VSCode Conventional Commits
• phpstrom
  • Conventional Commit
  • Git Commit Template

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 should be branch-based and commit messages should following Conventional Commits.

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

• symplify/monorepo-builder
  • Keeps packages versions in sync.
  • Config is located in monorepo-builder. It allows to define more dependencies
• semantic-release
  • Handle the release process from a Github action.

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

• hraban/tomono

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

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)

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.

• Locomotive 🚂
• Mathieu Ducharme 👨🏻‍💻
• Chauncey McAskill 👨🏻‍💻
• Joel Alphonso 👨🏻‍💻
• Dominic Lord 👨🏻‍💻
• Benjamin Roch 👨🏻‍💻

Made with contrib.rocks.

View CHANGELOG.

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

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