feat: root level CONTRIBUTING.md

Author: bd82

CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# Contribution Guide
+
+This is the common top-level contribution guide for this monorepo.
+A sub-package **may** have an additional CONTRIBUTING.md file if needed.
+
+## Legal
+
+All contributors must sign the DCO
+
+- https://cla-assistant.io/SAP-samples/ecmascript-monorepo-template
+
+This is managed automatically via https://cla-assistant.io/ pull request voter.
+
+## Development Environment
+
+### pre-requisites
+
+- [Yarn](https://yarnpkg.com/lang/en/docs/install/) >= 1.4.2
+- A [Long-Term Support version](https://nodejs.org/en/about/releases/) of node.js
+- (optional) [commitizen](https://github.com/commitizen/cz-cli#installing-the-command-line-tool) for managing commit messages.
+
+### Initial Setup
+
+The initial setup is trivial:
+
+- clone this repo
+- `yarn`
+
+### Commit Messages format.
+
+This project enforces the [conventional-commits][conventional_commits] commit message formats.
+The possible commits types prefixes are limited to those defined by [conventional-commit-types][commit_types].
+This promotes a clean project history and enabled automatically generating a changelog.
+
+The commit message format will be inspected both on a git pre-commit hook
+and during the central CI build and will **fail the build** if issues are found.
+
+It is recommended to use `git cz` to construct valid conventional commit messages.
+
+- requires [commitizen](https://github.com/commitizen/cz-cli#installing-the-command-line-tool) to be installed.
+
+[commit_types]: https://github.com/commitizen/conventional-commit-types/blob/master/index.json
+[conventional_commits]: https://www.conventionalcommits.org/en/v1.0.0/
+
+### Formatting.
+
+[Prettier](https://prettier.io/) is used to ensure consistent code formatting in this repository.
+This is normally transparent as it automatically activated in a pre-commit hook using [lint-staged](https://github.com/okonet/lint-staged).
+However, this does mean that dev flows that do not use a full dev env (e.g editing directly on github)
+may result in voter failures due to formatting errors.
+
+### Compiling
+
+Use the following npm scripts at the repo's **root** to compile **all** the TypeScript sub-packages.
+
+- `yarn compile`
+- `yarn compile:watch` (will watch files for changes and re-compile as needed)
+
+These scripts may also be available inside the sub-packages. However, it is recommended to
+use the top-level compilation scripts to avoid forgetting to (re-)compile a sub-package's dependency.
+
+### Testing
+
+[Mocha][mocha] and [Chai][chai] are used for unit-testing and [Istanbul/Nyc][istanbul] for coverage reports.
+
+[mocha]: https://mochajs.org/
+[chai]: https://www.chaijs.com
+[istanbul]: https://istanbul.js.org/
+
+- To run the tests execute `yarn test` in a specific sub-package.
+- To run the tests with **coverage** run `yarn coverage` in a specific sub-package.
+
+### Code Coverage
+
+100%\* Code Coverage is enforced for all productive code in this mono repo.
+
+- Specific statements/functions may be [excluded][ignore_coverage] from the report.
+  - However, the reason for each exclusion must be documented.
+
+[ignore_coverage]: https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md
+
+### Full Build
+
+To run the full **C**ontinuous **I**ntegration build run `yarn ci` in either the top-level package or a specific subpackage.
+
+### Release Life-Cycle.
+
+This monorepo uses Lerna's [Fixed/Locked][lerna-mode] which means all the sub-packages share the same version number.
+
+[lerna-mode]: https://github.com/lerna/lerna#fixedlocked-mode-default
+
+### Release Process
+
+Performing a release requires push permissions to the repository.
+
+- Ensure you are on the default branch and synced with origin.
+- `yarn run release:version`
+- Follow the lerna CLI instructions.
+- Track the newly pushed **tag** (`/^v[0-9]+(\.[0-9]+)*/`) build in the build system
+  until successful completion.
+- Inspect the newly artifacts published on npmjs.com / Github Releases / other relevant release targets.

README.md

@@ -26,14 +26,18 @@ The consumption process is currently a **manual** step by step guide.
    - Note that some sub-packages depend on other sub-packages.
 1. Change the `name` fields of the remaining `packages/*/package.json` files to fit your new project.
 
+1. Delete the **contents** of the README.md files in both the root and the sub-packages.
+
 1. Reset the `version` field in the [lerna.json](./lerna.json) to your project's **initial** version number.
 
    - Normally `0.1.0` or `0.0.1`.
 
 1. Adjust **coverage thresholds** in the [nyc.config.js](./nyc.config.js).
    - By default, these are set to **100%**.
+1. Adjust [CONTRIBUTING.md code coverage section](./CONTRIBUTING.md#code-coverage).
+   - To align with the **coverage thresholds** defined in the [nyc.config.js](./nyc.config.js).
+   - Modify the `cla-assistant` link in the [CONTRIBUTING.md legal section](./CONTRIBUTING.md#legal).
 1. Update the Legal Related files (copyrights/notices/disclaimer).
-
    - [./.reuse/dep5](./.reuse/dep5)
    - [./LICENSES](./LICENSES)
    - [./LICENSE](./LICENSE)
@@ -45,6 +49,13 @@ The consumption process is currently a **manual** step by step guide.
 1. If you kept VSCode extension templates, also adjust the `displayName` and `publisher` fields
    in their `package.json` files to fit your new project.
 1. If you have not kept any VSCode extensions in your monorepo, remove the [root vscode webpack config](./webpack.config.vscode.base.js).
+
+1. Adjust the [circle-ci config.yml](./.circleci/config.yml).
+   There are three possible sections that may need to be removed (and their references):
+
+   - `deploy-npm` --> if your project should not deploy any npm library to npmjs.com.
+   - `prepare-vsix` and `deploy-gh-releases` --> if your project does not include VSCode extensions.
+
 1. Adjust the [.eslintrc.js](./.eslintrc.js) configuration.
 
    - Remove `overrides` sections for no longer relevant file types:
@@ -55,12 +66,14 @@ The consumption process is currently a **manual** step by step guide.
      - `eslint-plugin-vue` --> if your monorepo does not contain any vue frontend projects.
 
 1. Adjust root TypeScript configurations.
+
    - Remove sub-project references that no longer exist from [root ./tsconfig.json](./tsconfig.json).
    - If there are no references left in this file, and you do not plan on adding TypeScript projects
      to your monorepo:
      - Delete the [root ./tsconfig.json](./tsconfig.json).
      - Delete the [root ./tsconfig.base.json](./tsconfig.base.json).
      - Remove the `compile` and `compile:watch` scripts from the [root package.json](./packages).
+
 1. Adjust lint-staged configurations.
    - Look for the `lint-staged` field and its keys in the [root package.json](./package.json).
    - Remove file patterns that your repo no longer contains (or is expected to contain).
@@ -81,7 +94,7 @@ Please open an [issue](https://github.com/SAP-samples/ecmascript-monorepo-templa
 
 ## Contributing
 
-Contributions are very welcome.
+Contributions are most welcome.
 Please see the [Templates Contributing Guide](TBD).
 
 ## License

package.json

@@ -8,7 +8,7 @@
   },
   "scripts": {
     "postinstall": "patch-package",
-    "release:version": "lerna version && yarn run cirlce:release",
+    "release:version": "lerna version",
     "release:publish": "lerna publish from-git --yes",
     "ci": "npm-run-all format:validate lint:validate legal:* ci:subpackages coverage:merge",
     "ci:subpackages": "lerna run ci",