fix(docs): write a basic readme
This commit is contained in:
parent
64621f7f10
commit
9c5b750c15
GPG Key ID:
3EED7B957D362AF1
210
README.md
210
README.md
|
|
@ -1,149 +1,117 @@
|
|||
# Rollup Template
|
||||
# JS Utils
|
||||
|
||||
This project contains the configuration and build scripts for most of
|
||||
my Typescript projects, with scripts to create a new project and keep
|
||||
existing ones up-to-date. Even this readme is a template for others.
|
||||
|
||||
## Features
|
||||
|
||||
- build scripts with `make`
|
||||
- build pipeline with `gitlab`
|
||||
- update github commit status
|
||||
- publish docker images from branches & tags
|
||||
- publish npm packages from tags
|
||||
- bundled with `rollup`
|
||||
- type checked with `typescript`
|
||||
- style checked with `eslint` (with `tslint` rules and other plugins)
|
||||
- tested with `mocha` (with source map support and helpers for async leak tracking)
|
||||
- code coverage measured with `nyc`
|
||||
- changelog generated with `standard-release`
|
||||
|
||||
### Intentionally Omitted Features
|
||||
|
||||
- everything frontend: React, CSS, etc
|
||||
- heavy backend libraries: ORMs, etc
|
||||
This project is a collection of utilities meant to extend lodash, collected from my
|
||||
other Typescript projects, lightly documented, and heavily tested.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Rollup Template](#rollup-template)
|
||||
- [Features](#features)
|
||||
- [Intentionally Omitted Features](#intentionally-omitted-features)
|
||||
- [JS Utils](#js-utils)
|
||||
- [Contents](#contents)
|
||||
- [Status](#status)
|
||||
- [Releases](#releases)
|
||||
- [Usage](#usage)
|
||||
- [To Setup](#to-setup)
|
||||
- [To Build](#to-build)
|
||||
- [To Release](#to-release)
|
||||
- [External Services](#external-services)
|
||||
- [Maintenance Bots](#maintenance-bots)
|
||||
- [External Secrets](#external-secrets)
|
||||
- [Features](#features)
|
||||
|
||||
## Status
|
||||
|
||||
[](https://git.apextoaster.com/ssube/rollup-template/commits/master)
|
||||
[](https://sonarcloud.io/dashboard?id=ssube_rollup-template)
|
||||
[](https://codecov.io/gh/ssube/rollup-template)
|
||||
[](https://github.com/ssube/rollup-template/blob/master/LICENSE.md)
|
||||
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fssube%2Frollup-template?ref=badge_shield)
|
||||
[](https://git.apextoaster.com/ssube/js-utils/commits/master)
|
||||
[](https://sonarcloud.io/dashboard?id=ssube_js-utils)
|
||||
[](https://codecov.io/gh/ssube/js-utils)
|
||||
[](https://github.com/ssube/js-utils/blob/master/LICENSE.md)
|
||||
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fssube%2Fjs-utils?ref=badge_shield)
|
||||
|
||||
[](https://github.com/ssube/rollup-template/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fbug)
|
||||
[](https://github.com/ssube/rollup-template/issues?q=is%3Aopen+is%3Aissue)
|
||||
[](https://github.com/ssube/rollup-template/issues?q=is%3Aissue+is%3Aclosed)
|
||||
[](https://github.com/ssube/js-utils/issues?q=is%3Aopen+is%3Aissue+label%3Atype%2Fbug)
|
||||
[](https://github.com/ssube/js-utils/issues?q=is%3Aopen+is%3Aissue)
|
||||
[](https://github.com/ssube/js-utils/issues?q=is%3Aissue+is%3Aclosed)
|
||||
|
||||
[](https://renovatebot.com)
|
||||
[](https://david-dm.org/ssube/rollup-template)
|
||||
[](https://david-dm.org/ssube/rollup-template?type=dev)
|
||||
[](https://snyk.io/test/github/ssube/rollup-template)
|
||||
[](https://renovatebot.com)
|
||||
[](https://david-dm.org/ssube/js-utils)
|
||||
[](https://david-dm.org/ssube/js-utils?type=dev)
|
||||
[](https://snyk.io/test/github/ssube/js-utils)
|
||||
|
||||
[](https://codeclimate.com/github/ssube/rollup-template/maintainability)
|
||||
[](https://codeclimate.com/github/ssube/rollup-template/trends/technical_debt)
|
||||
[](https://codeclimate.com/github/ssube/rollup-template/issues)
|
||||
[](https://lgtm.com/projects/g/ssube/rollup-template/context:javascript)
|
||||
[](https://lgtm.com/projects/g/ssube/rollup-template/alerts/)
|
||||
[](https://codeclimate.com/github/ssube/js-utils/maintainability)
|
||||
[](https://codeclimate.com/github/ssube/js-utils/trends/technical_debt)
|
||||
[](https://codeclimate.com/github/ssube/js-utils/issues)
|
||||
[](https://lgtm.com/projects/g/ssube/js-utils/context:javascript)
|
||||
[](https://lgtm.com/projects/g/ssube/js-utils/alerts/)
|
||||
|
||||
## Releases
|
||||
|
||||
[](https://github.com/ssube/rollup-template/releases)
|
||||
[](https://github.com/ssube/rollup-template/releases)
|
||||
[](https://github.com/ssube/rollup-template/compare/v0.2.4...master)
|
||||
[](https://github.com/ssube/js-utils/releases)
|
||||
[](https://github.com/ssube/js-utils/releases)
|
||||
[](https://github.com/ssube/js-utils/compare/v0.1.6...master)
|
||||
|
||||
[](https://www.npmjs.com/package/@apextoaster/rollup-template)
|
||||
[](https://www.npmjs.com/package/@apextoaster/rollup-template)
|
||||
[](https://www.npmjs.com/package/@apextoaster/rollup-template)
|
||||
[](https://www.npmjs.com/package/@apextoaster/js-utils)
|
||||
[](https://www.npmjs.com/package/@apextoaster/js-utils)
|
||||
[](https://www.npmjs.com/package/@apextoaster/js-utils)
|
||||
|
||||
## Usage
|
||||
|
||||
### To Setup
|
||||
Install:
|
||||
|
||||
To create a new repository from this template:
|
||||
```shell
|
||||
yarn add -D @apextoaster/js-utils
|
||||
```
|
||||
|
||||
- create your new repo on Github & Gitlab (your server or Gitlab.com)
|
||||
- `git clone git@github.com:ssube/rollup-template.git your-project`
|
||||
- `cd your-project`
|
||||
- `git remote add github git@github.com:yourname/your-project.git`
|
||||
- `git remote add gitlab git@gitlab.com:yourname/your-project.git`
|
||||
- set up repository mirroring in Gitlab
|
||||
- set up [some maintenance bots](#maintenance-bots)
|
||||
- `make git-push`
|
||||
- install your dependencies
|
||||
- write some code
|
||||
And import:
|
||||
|
||||
### To Build
|
||||
```typescript
|
||||
import { mustExist } from '@apextoaster/js-utils';
|
||||
```
|
||||
|
||||
Once your project is set up:
|
||||
The library is bundled and depends on lodash, linked in a vendor module.
|
||||
|
||||
- `make` to bundle and test
|
||||
- commit
|
||||
- `make git-push`
|
||||
## Features
|
||||
|
||||
The `git-push` target pushes to Github first, to avoid conflicts with changes
|
||||
from bots and other contributors.
|
||||
- array mapper
|
||||
- map elements to keys by order
|
||||
- skip initial, gather remaining
|
||||
- async
|
||||
- defer
|
||||
- promise timeout
|
||||
- wait for predicate
|
||||
- async tracker
|
||||
- track and log leaking async resources for tests
|
||||
- buffer
|
||||
- checklist
|
||||
- include/exclude mode (whitelist/blacklist)
|
||||
- child process
|
||||
- wait for exit and gather output
|
||||
- write and flush
|
||||
- env
|
||||
- check `DEBUG`
|
||||
- list
|
||||
- concat lists
|
||||
- logger
|
||||
- get test logger (null or console depending on `DEBUG`)
|
||||
- map
|
||||
- must get (assertion)
|
||||
- get or default
|
||||
- get head from list value
|
||||
- get head or default
|
||||
- set or push to key
|
||||
- merge maps
|
||||
- push-merge maps
|
||||
- convert dict to map and vice versa
|
||||
- normalize map values to lists
|
||||
- create map from name-value pairs
|
||||
- maybe
|
||||
- is nil test (negative nil test)
|
||||
- count array or maybe
|
||||
- filter nil from list
|
||||
- must find (assertion)
|
||||
- does exist (positive nil test)
|
||||
- must exist (assertion)
|
||||
- must default (assertion)
|
||||
- pid file
|
||||
- write pid file
|
||||
- delete pid file
|
||||
- reflect
|
||||
- get constructor name
|
||||
- get methods from prototype chain
|
||||
- signals
|
||||
- wait for OS signal
|
||||
- string
|
||||
- left pad (please don't import just for this)
|
||||
- trim with suffix
|
||||
|
||||
### To Release
|
||||
|
||||
When your project is ready to release:
|
||||
|
||||
- `make release-dry` to make sure your changelog and options look right
|
||||
- `make release`
|
||||
|
||||
Additional options can be passed with the `RELEASE_OPTS` variable. Frequently
|
||||
used options include `--release-as minor` and `--prerelease`.
|
||||
|
||||
## External Services
|
||||
|
||||
This template works with or expects a few external services, namely a Gitlab
|
||||
CI server (self-hosted or using Gitlab.com).
|
||||
|
||||
### Maintenance Bots
|
||||
|
||||
Good tests and clever bots can eliminate the most painful parts of project
|
||||
maintenance. This repository is configured to work with:
|
||||
|
||||
- [CodeCov](https://codecov.io/)
|
||||
- [Code Climate](https://codeclimate.com/)
|
||||
- [LGTM](https://lgtm.com/)
|
||||
- [Renovate](https://renovatebot.com/)
|
||||
- [Snyk](https://snyk.io/)
|
||||
- [SonarCloud](https://sonarcloud.io/)
|
||||
|
||||
None of these are required, but Renovate and Snyk can be very helpful when
|
||||
dependencies release a security patch.
|
||||
|
||||
## External Secrets
|
||||
|
||||
This template expects a few secrets to exist in the environment, including
|
||||
tokens for the [external services](#external-services).
|
||||
|
||||
| Name | Description |
|
||||
| ------------------- | ----------------------------------------------------- |
|
||||
| CC_TEST_REPORTER_ID | code climate ID |
|
||||
| CODECLIMATE_SECRET | code climate token |
|
||||
| CODECOV_SECRET | codecov token |
|
||||
| DOCKER_SECRET | docker config, required for publishing images |
|
||||
| GITHUB_SECRET | github.com token, required for publishing status |
|
||||
| NPM_SECRET | npmjs.com token, required for publishing npm packages |
|
||||
| SONAR_SECRET | sonarcloud token |
|
||||
|
||||
Secrets should be provided as environment variables, with the secret value
|
||||
`base64`-encoded.
|
||||
|
|
|
|||
Loading…
Reference in New Issue