Monorepo with Remark packages #12
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
>> 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
svengreb
approved these changes
Apr 2, 2021
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves #10