Commits on Apr 2, 2021

1. Monorepo with Remark packages …

   >> Previous Project State
   
   Before the repository only contained the actual style guide
   documentation while specific projects that implement the guidelines for
   linters and code style analyzer live in separate repositories.
   This was the best approach for modularity and a small and clear code
   base, but it increases the maintenance overhead by 1(n) since changes to
   the development workflow or toolbox, general project documentations as
   well as dependency management requires changes in every repository with
   dedicated tickets/issues and PRs. In particular, Node packages require
   frequent dependency management due to their fast development cycles to
   keep up-to-date with the latest package changes like (security) bug
   fixes.
   
   This style guide is currently implemented by the
   remark-preset-lint-arcticicestudio [1] Node package that lived in its
   own repository. The development workflow was clean using most of
   GitHub's awesome features like project boards, codeowner assignments,
   issue & PR automation and so on, but changes often require multiple
   actions when packages depend on each other or they use the same
   development tooling and documentation standards.
   
   >>> Monorepo Comparison
   
   Monorepos [2] are a fantastic way to manage such a project structure,
   but there are also some points that must be taken into account:
   
   - No more scoped code - the developer experience with Git is slightly
     worse because commits can contains changes to multiple scopes of the
     code. Since there is only a "transparent separation” of code, that was
     previously located in a dedicated repository but is not aggregated
     into a parent (e.g. `packages`) with other modules, commits can now
     contain changes to multiple code scopes spread over the entire code
     base.
   - No more assignment of commits to single modules - like described in
     the bullet point above, commit can contain changes to multiple
     modules, it is harder to detect which commit targeted a specific
     module.
   - Steeper learning curve for new contributors - in a dedicated
     repository that only hosts a specific module it is easier for new
     developers to contribute to the project, but in a monorepo they
     might need to change code in multiple places within other modules or
     the root code/documentation of the entire project.
   - Uniform version number - in order to keep conform to SemVer [3],
     the entire project must use a uniform version number. This means that
     a module that has not been changed since the last version must also be
     incremented in order to keep compatible with the other modules.
     Using different version numbers prefixed/suffixed with an individual
     version number is a not an option, increases the maintenance overhead
     and and drastically reduces the project overview and quality!
     This would result in multiple Git tags on the `main` branch as well as
     "empty” changelogs and release notes with placeholder logs that only
     refer to changes of other modules.
   
   >> Project Future
   
   Even though a monorepo requires some special thoughts, it also comes
   with a lot of benefits and makes sense for specific project modules that
   are slightly coupled and where using dedicated repositories only
   increases the maintenance overhead when changes must be reflected in
   multiple modules anyway.
   
   In order to reduce the maintenance overhead,
   the remark-preset-lint-arcticicestudio [1] Node package has been
   migrated into this repository by adapting to Yarn workspaces [4].
   This simplifies the development tooling setup and allows to use a
   unified documentation base as well as a smoother development and testing
   workflow.
   
   This change also implies that the root of the repository is now the main
   package for the entire project setup including shared development
   dependencies, tools and documentations while the packages only contain
   specific configurations and (dev)dependencies.
   
   >>> Scoped Packages
   
   Before the remark-preset-lint-arcticicestudio [1] package was not a
   scoped package [5] but suffixed with `-arcticicestudio`. To simplify the
   naming and improving the usage of user/organization specific packages,
   it is now scoped to `@arcticicestudio` resulting in the new name
   `@arcticicestudio/remark-preset-lint`.
   The currently released public version will be deprecated using the
   `npm deprecate` command [6] where the provided message will point out to
   migrate to the new scoped packages.
   
   >>> Versioning
   
   The style guide itself and all packages now use a shared/fixed/locked
   version. This helps all packages to keep in sync and ensure the
   compatibility with the latest style guide version.
   
   [1]: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio
   [2]: https://trunkbaseddevelopment.com/monorepos
   [3]: https://semver.org
   [4]: https://yarnpkg.com/en/docs/workspaces
   [5]: https://docs.npmjs.com/about-scopes
   [6]: https://docs.npmjs.com/cli/deprecate
   
   Co-authored-by: Sven Greb <development@svengreb.de>
   
   GH-10

   

   arcticicestudio committed Apr 2, 2021
   Configuration menu

   • View commit details
   • Copy full SHA for b545f77
   • Browse repository at this point

   Copy the full SHA

   b545f77 View commit details

   Browse the repository at this point in the history