Reset as monorepo

[joshbruce]

Describe the feature

• All you always wanted to know about monorepos
• What is monorepo?

Why is this feature necessary?

The following packages are all related to generating, compelling, and validating markup in some way:

• https://github.com/8fold/php-xml-builder
• https://github.com/8fold/php-html-builder
• https://github.com/8fold/php-feed-builder
• https://github.com/8fold/php-html-spec-compiler
• https://github.com/8fold/php-html-spec
• https://github.com/8fold/laravel-markup

There are even some archived repos as we continue to try and figure out how to store and manage this work:

• https://github.com/8fold/php-html-component
• https://github.com/8fold/php-html

Believe it would be easier and more robust to maintain using a monorepo construct:

• php-markup
  • php-xml-builder (Xml)
  • php-html-builder (Html)
  • ? php-html-spec (HtmlCli)
  • php-html-components (HtmlComponents)
  • ? laravel-html-components (LaravelComponents)
  • ? uswds-html-components (UswdsComponents)
  • php-feed-builder (Feed)

Those prefixed with question marks (?) either haven't been developed or would be viable additions.

Describe alternatives you've considered

The multiple repository approach has been the method used to date and it's proving to be difficult to maintain.

We tried consolidating all the work under this repository at one time; however, this meant consumers would need to bring in a fair amount of dependencies that may not be necessary for their projects.

Benefits to keep

• Anyone can easily contribute to the codebase.
• Multiple repositories (read-only) and consumable packages.
• Main is always deployable.

Benefits we'd like to keep

• Packages can follow semantic versioning.
  • My understanding of monorepo releases is that each package has the same version as the root project. A major release to the monorepo means a major release for each internal package, even if there were no changes to that codebase.
• Individual READ ME files for each package.
  • Often when I see packages split off from a monorepo they simply say READ ONLY and don't submit PRs to this repo. Symfony seems to have the most robust ecosystem and setup; however, Symfony has READ ME files for each component repository. (?? Is the PR history from direct contribution or from submissions to the monorepo)
  • Laravel framework has a viable setup. Though the subtree split repositories don't hold a full READ ME.

Pain points to alleviate

• Many of these libraries are dependent on one another.
• A combination of these libraries are used in most 8fold web projects (see php-amos.
• It's not easy to see the impact of changes and bug fixes across the projects. Instead we wither use the -dev branches or * when adding or changing functionality.
• Setting up new repos is cumbersome.
  • Despite having a repo template it can still feel cumbersome. Also, updating the repo template doesn't automatically make changes to the other repos. Having most of the individual projects under "one roof" that then distributes seems like a viable alternative.

It's okay if we lost

• Commit histories
• Issues and PRs from other repos

Tools to consider

• Monorepo builder - PHP solution