-
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.
- Loading branch information
Showing
7 changed files
with
203 additions
and
133 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
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,65 @@ | ||
| # 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. | ||
|
|
||
| ## Content | ||
| 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 <!-- omit in toc --> | ||
|
|
||
| - [Architecture](#architecture) | ||
| - [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 bundled code. | ||
|
|
||
| The documentation could: | ||
| The used node version is 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`). |
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
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,51 +1,88 @@ | ||
| # Deployment | ||
|
|
||
| <!-- | ||
| This chapter should provide the user with all needed information around the deployment of your project. Please provide a short introduction here. | ||
| --> | ||
| The documentation skeleton project will be deployed on every update of the main branch. | ||
|
|
||
| ## Content | ||
| ## Content <!-- omit in toc --> | ||
|
|
||
| - [Deployment](#deployment) | ||
| - [Tooling](#tooling) | ||
| - [Release Please](#release-please) | ||
| - [Conventional Commit Messages](#conventional-commit-messages) | ||
| - [How to deploy](#how-to-deploy) | ||
| - [Versioning](#versioning) | ||
| - [Release Management](#release-management) | ||
| - [Deployment Schedule](#deployment-schedule) | ||
| - [Support](#support) | ||
|
|
||
| ## Tooling | ||
|
|
||
| <!-- | ||
| Please explain what kind of tools you use for your deployment, why you have choosen them and how to work with them. | ||
| --> | ||
| This project uses release-please and conventional commit messages for automated release creation and deploys the package to the npm registry. | ||
|
|
||
| We use the [Git-Flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) branching model: | ||
|
|
||
| ```mermaid | ||
| gitGraph | ||
| commit id: "a" | ||
| commit id: "b" | ||
| branch develop | ||
| checkout develop | ||
| checkout develop | ||
| branch feature1 | ||
| checkout feature1 | ||
| commit id: "c" | ||
| checkout develop | ||
| merge feature1 | ||
| branch feature2 | ||
| checkout feature2 | ||
| commit id: "d" | ||
| checkout develop | ||
| merge feature2 | ||
| checkout main | ||
| merge develop | ||
| branch "release" | ||
| checkout release | ||
| commit id: "1.0.0" tag: "release" | ||
| checkout main | ||
| merge release | ||
| checkout develop | ||
| merge main | ||
| ``` | ||
|
|
||
| ### Release Please | ||
|
|
||
| Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects. Release Please does so by parsing the git history, looking for Conventional Commit messages, and creating release PRs. | ||
|
|
||
| The tool runs on every update on the `main` branch and creates a release PR which needs to be manually be merged to create the release. | ||
|
|
||
| The updated `main` branch then needs to be merged back, please use rebase, into the `develop` branch. | ||
|
|
||
| Due to the open source nature of this project it was decided it is best to have a `develop` branch to test all new features together before an official release is created. | ||
|
|
||
| ### Conventional Commit Messages | ||
|
|
||
| We use [Conventional Commit messages](https://www.conventionalcommits.org/en/v1.0.0/) to be able to create changelog and version bumps automatically. | ||
|
|
||
| We have a pre-push hook installed that uses [commit lint](https://github.com/conventional-changelog/commitlint) to verify the commits messages are following the conventional commit message standard. | ||
|
|
||
| ## How to deploy | ||
|
|
||
| <!-- | ||
| In this section you should discribe the deployment process for your project. Think about how developers who are unfamiliar with the project can deploy it to the respective enviroments. | ||
| --> | ||
| One needs to create a new PR from `develop` to `main`. Once the PR is approved and merged the GitHub workflow `release` will be started. | ||
|
|
||
| ## Versioning | ||
| The `release` workflow will first run the tests and after they were successful a new release branch is created together with a PR from the release branch into `main`. | ||
|
|
||
| <!-- | ||
| Please describe briefly how you manage the versioning of your project. | ||
| --> | ||
| Lastly a notification for the internal slack channel is created. | ||
|
|
||
| ## Release Management | ||
| The newly created release PR needs to be manually merged into main to finish the package creation and release publishing. | ||
|
|
||
| After the release PR is merged the `develop` branch also needs to be updated by rebasing it onto the `main` branch. | ||
|
|
||
| ## Versioning | ||
|
|
||
| <!-- | ||
| If you have a release management setup in place, please describe the process and who to contact if support is needed. | ||
| --> | ||
| Please see [conventional commit messages](#conventional-commit-messages) | ||
|
|
||
| ## Deployment Schedule | ||
|
|
||
| <!-- | ||
| Please write down your deployment schedule. Consider using screenshots or graphs for better visualization. | ||
| --> | ||
| There is no deployment schedule. A new release is created whenever we have multiple new small features or a new big feature that we want to release. | ||
|
|
||
| ## Support | ||
|
|
||
| <!-- | ||
| If someone needs support while deploying your project, please list the possible contact persons or communication channels where people can get support. | ||
| --> | ||
| If you need support with the release process please [create an issue](https://github.com/deven-org/hamster/issues) or get in touch with [Jumace](https://github.com/Jumace). |
Oops, something went wrong.