-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add architecture documentation
- Loading branch information
Showing
1 changed file
with
48 additions
and
19 deletions.
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,37 +1,66 @@ | ||
| # Architecture | ||
|
|
||
| <!-- | ||
| This chapter should provide the user with as much information as possible about the architecture and overall structure of your project. Please provide a short introduction here. | ||
| --> | ||
| The documentation skeleton can be integrated in multiple ways into other projects, the recommended way is to add it as a devDependency. | ||
|
|
||
| As an npm package the project has also multiple commands that can be executed. | ||
|
|
||
| In this document one can find more information about the npm package and command architecture. | ||
|
|
||
| ## Content | ||
|
|
||
| - [Architecture](#architecture) | ||
| - [Content](#content) | ||
| - [Overall Structure](#overall-structure) | ||
| - [Entry script](#entry-script) | ||
| - [The commands](#the-commands) | ||
| - [Shared](#shared) | ||
| - [Technical Decisions](#technical-decisions) | ||
| - [APIs](#apis) | ||
|
|
||
| ## Overall Structure | ||
|
|
||
| <!-- | ||
| Please explain the overall structure of your project and how everything works together. You can use screenshots or code snippets to help visualize things like e.g. your folder structure or the project setup. In this chapter you can be as detailed as you like. | ||
| --> | ||
| The project consists of multiple parts, in the contribution guide one can find an overview of the [file structure](/docs/CONTRIBUTE.md#📁-file-structure). | ||
|
|
||
| ### Entry script | ||
|
|
||
| The entry script can be found under `bin/index.js`. | ||
|
|
||
| This script is a wrapper for the commands implemented under `src/commands`. | ||
|
|
||
| Because the script is a wrapper it was decided to leave it in plain JavaScript. | ||
|
|
||
| The script imports/requires the commands from the UMD bundle out of the build folder. | ||
|
|
||
| The script checks the call parameters and depended on them calls one of the commands. | ||
|
|
||
| ### The commands | ||
|
|
||
| The documentation skeleton project has three different commands to support with your own documentation structure. | ||
|
|
||
| The commands are written in TypeScript and with `microbundle` bundled into a UMD module. | ||
|
|
||
| Each command has a number of tests, which can be found in the directory `__tests__`. | ||
|
|
||
| ### Shared | ||
|
|
||
| The `shared` folder contains the messages that are used by the different commands to communicate with the user. | ||
|
|
||
| ## Technical Decisions | ||
|
|
||
| <!-- | ||
| In this section you should list all technical things you use like frameworks, tools, languages and provide explanations of why you have chosen them. Think about e.g. what are the main reasons you choose a framework, what are the advantages you need for your project? Try to be as clear as possible so also new joiners understand why your setup is the best for your project. | ||
| --> | ||
| The project is bundled to a UMD module with the help of `microbundle`. | ||
|
|
||
| As this is an open source project we aim for a test coverage of >90%, experience showed that it good to cover as much as possible with tests. | ||
|
|
||
| We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) and enforce them with a hook that checks the commit message after creation with [commitlint](https://github.com/conventional-changelog/commitlint) | ||
|
|
||
| The `pre-push` hook is used to run linting ([ESLint](https://eslint.org/)), formatting ([prettier](https://prettier.io/)) and testing ([Jest](https://jestjs.io/)). | ||
| If any part of the hook is failing the code can not be pushed before the required changes are implemented. | ||
|
|
||
| ## APIs | ||
| If a work-in-progress should be pushed one can use the `--no-verify` flag on the push command but this bypass should only be used if needed. | ||
|
|
||
| <!-- | ||
| Please describe briefly how you manage the APIs of your project and how to use them. | ||
| The package uses itself for the documentation, therefore we have multiple `self*` commands. | ||
| To use those commands a build needs to be done beforehand as it is calling the bundles code. | ||
|
|
||
| The documentation could: | ||
| The used node version os 18, due to a problem with the `mock-fs` dependency. The dependency is not compatible with node 20 yet. | ||
| Due to that we set the required node version between 16.20.2 and 20.0.0. | ||
|
|
||
| - describe the data structures, functions, arguments, return types, classes, payloads, etc., developers can refer to. | ||
| - refer to other existing resources (git repos, websites, etc.) | ||
| - if you are using one or more tools, describe how to install / access / use them | ||
| - how to test the APIs locally | ||
| --> | ||
| To make sure that the whole package can still be used by projects that use node >= 20.0.0 we delete the `engines` key out of the `package.json` before a publish happens and restore it afterwards again (see `prepublishOnly` and `postpublish` in `package.json`). |