CONFDOCS.md

Codebase Configuration Documentation

Documents configuration tasks managed by robo-config.

Plugin @blackflux/robo-config-plugin

• 📂 assorted/@npm-opensource
  • 📂 struct/#npm-opensource
    • 📋 struct/template-readme
    • 📋 struct/template-mocha-opts
    • 📋 struct/template-index-test
    • 📋 struct/template-index
    • 📋 struct/template-eslintrc
    • 📋 struct/template-babelrc
  • 📂 semantic-release/#npm-opensource
    • 📋 semantic-release/commit-conventions
  • 📂 package/#npm-opensource
    • 📋 package/merge-shallow
    • 📋 package/merge-deep
    • 📋 package/default-shallow
    • 📋 package/default-deep
  • 📂 npm/#npm-opensource
    • 📋 npm/npmignore
  • 📂 license/#npm-opensource
    • 📂 license/@MIT-npm
      • 📋 license/MIT-package
      • 📋 license/MIT-file
  • 📂 jetbrains/#npm-opensource
    • 📋 jetbrains/exclude-coverage-folder
  • 📂 git/#npm-opensource
    • 📋 git/gitignore
  • 📂 gally/#npm-opensource
    • 📋 gally/two-branch
  • 📂 editor/#npm-opensource
    • 📋 editor/two-space
  • 📂 dependabot/#npm-opensource
    • 📋 dependabot/js-instant
  • 📂 circleci/#npm-opensource
    • 📋 circleci/two-branch
  • 📂 badges/#npm-opensource
    • 📋 badges/semantic-release
    • 📋 badges/npm-status
    • 📋 badges/npm-downloads
    • 📋 badges/js-gardener
    • 📋 badges/dependabot
    • 📋 badges/david-dm
    • 📋 badges/coveralls
    • 📋 badges/circleci

📂 assorted/@npm-opensource (index)

Manage various configuration files for an open source npm package on github.

Targets	Requires	Variables
project ├─ .babelrc ├─ .circleci │  └─ config.yml ├─ .dependabot │  └─ config.yml ├─ .editorconfig ├─ .eslintrc.json ├─ .gally.json ├─ .gitignore ├─ .idea │  └─ ${projectName}.iml ├─ .npmignore ├─ .releaserc.json ├─ LICENSE ├─ package.json ├─ README.md ├─ src │  └─ index.js └─ test    ├─ index.spec.js    └─ mocha.opts	javascript mocha chai eslint babel semantic-release npm jetbrains nyc git circleci gally github dependabot yarn coveralls npm-published js-gardener david-dm	packageName repoKey ownerName projectName owner mergeBot

📂 struct/#npm-opensource (index)

Manage basic project structure for npm open source package on github.

Targets	Requires	Variables
project ├─ .babelrc ├─ .eslintrc.json ├─ README.md ├─ src │  └─ index.js └─ test    ├─ index.spec.js    └─ mocha.opts	javascript mocha chai eslint babel	packageName

📋 struct/template-readme (index)

Updating README.md using create-only.

• Create README.md template file.

Targets	Variables
project └─ README.md	packageName

📋 struct/template-mocha-opts (index)

Updating test/mocha.opts using create-only.

• Create options file for mocha tests.

Targets	Requires
project └─ test    └─ mocha.opts	javascript mocha

📋 struct/template-index-test (index)

Updating test/index.spec.js using create-only.

• Create package template index.spec.js test file.

Targets	Requires
project └─ test    └─ index.spec.js	javascript chai

📋 struct/template-index (index)

Updating src/index.js using create-only.

• Create package template index.js file.

Targets	Requires
project └─ src    └─ index.js	javascript

📋 struct/template-eslintrc (index)

Updating .eslintrc.json using overwrite.

• Create configuration file for eslint enforcing opinionated, best practices.

Targets	Requires
project └─ .eslintrc.json	javascript eslint

📋 struct/template-babelrc (index)

Updating .babelrc using merge-deep.

• Create configuration file for babel.

Targets	Requires
project └─ .babelrc	javascript babel

📂 semantic-release/#npm-opensource (index)

Manage semantic-release configuration for npm open source package on github.

Targets	Requires
project └─ .releaserc.json	semantic-release

📋 semantic-release/commit-conventions (index)

Updating .releaserc.json using overwrite.

• Slightly extended release commit convention for semantic-release.

Targets	Requires
project └─ .releaserc.json	semantic-release

📂 package/#npm-opensource (index)

Manage package.json for npm open source package on github.

Targets	Requires	Variables
project └─ package.json	javascript	repoKey packageName

📋 package/merge-shallow (index)

Updating package.json using merge-shallow.

• Set various entries.

Targets	Requires
project └─ package.json	javascript

📋 package/merge-deep (index)

Updating package.json using merge-deep.

• Set various entries.

Targets	Requires	Variables
project └─ package.json	javascript	repoKey packageName

📋 package/default-shallow (index)

Updating package.json using default-shallow.

• Set defaults for various entries.

Targets	Requires
project └─ package.json	javascript

📋 package/default-deep (index)

Updating package.json using default-deep.

• Set defaults for various entries.

Targets	Requires
project └─ package.json	javascript

📂 npm/#npm-opensource (index)

Manage npm configuration for npm open source package on github.

Targets	Requires
project └─ .npmignore	npm

📋 npm/npmignore (index)

Updating .npmignore using unique-top.

• Inject comment into .npmignore explaining when to use it.

Targets	Requires
project └─ .npmignore	npm

📂 license/#npm-opensource (index)

Manage license configuration for npm open source package on github.

Targets	Requires	Variables
project ├─ LICENSE └─ package.json	npm	ownerName repoKey

📂 license/@MIT-npm (index)

Manage license configuration for npm open source package on github.

Targets	Requires	Variables
project ├─ LICENSE └─ package.json	npm	ownerName repoKey

📋 license/MIT-package (index)

Updating package.json using merge-shallow.

• Link MIT license file into npm configuration.

Targets	Requires	Variables
project └─ package.json	npm	ownerName repoKey

📋 license/MIT-file (index)

Updating LICENSE using overwrite.

• Generate MIT license file.

Targets	Variables
project └─ LICENSE	ownerName

📂 jetbrains/#npm-opensource (index)

Manage WebStorm configuration for npm open source package on github.

Targets	Requires	Variables
project └─ .idea    └─ ${projectName}.iml	jetbrains nyc	projectName

📋 jetbrains/exclude-coverage-folder (index)

Updating .idea/${projectName}.iml (if exists) using xml-merge.

• Mark coverage Folder as excluded in Jetbrains.

Targets	Requires	Variables
project └─ .idea    └─ ${projectName}.iml	jetbrains nyc	projectName

📂 git/#npm-opensource (index)

Manage gitignore configuration for npm open source package on github.

Targets	Requires
project └─ .gitignore	git

📋 git/gitignore (index)

Updating .gitignore using unique-top.

• Inject recommended entries into gitignore file.
• Default ignores for JetBrains IDE.
• Default ignores for OSX
• Default ignores for NodeJs

Targets	Requires
project └─ .gitignore	git

📂 gally/#npm-opensource (index)

Manage gally configuration for npm open source package on github.

Targets	Requires	Variables
project └─ .gally.json	circleci gally github	owner mergeBot repoKey

📋 gally/two-branch (index)

Updating .gally.json using overwrite.

• Restrictive two-branch gally config.

Targets	Requires	Variables
project └─ .gally.json	circleci gally github	owner mergeBot repoKey

📂 editor/#npm-opensource (index)

Manage editor configuration for npm open source package on github.

Targets
project └─ .editorconfig

📋 editor/two-space (index)

Updating .editorconfig using overwrite.

• Two space line indentation.
• Set lf line endings.
• Set utf8 encoding.
• Remove unnecessary whitespaces.

Targets
project └─ .editorconfig

📂 dependabot/#npm-opensource (index)

Manage dependabot configuration for npm open source package on github.

Targets	Requires
project └─ .dependabot    └─ config.yml	dependabot github javascript

📋 dependabot/js-instant (index)

Updating .dependabot/config.yml using overwrite.

• Configure dependabot to instantly merge javascript dependency updates into the dev branch.

Targets	Requires
project └─ .dependabot    └─ config.yml	dependabot github javascript

📂 circleci/#npm-opensource (index)

Manage circleci configuration for npm open source package on github.

Targets	Requires
project └─ .circleci    └─ config.yml	npm yarn gally github circleci coveralls dependabot semantic-release

📋 circleci/two-branch (index)

Updating .circleci/config.yml using overwrite.

• Restrictive two-branch gally config.

Targets	Requires
project └─ .circleci    └─ config.yml	npm yarn gally github circleci coveralls dependabot semantic-release

📂 badges/#npm-opensource (index)

Add badged for npm open source package on github.

Targets	Requires	Variables
project └─ README.md	semantic-release npm-published js-gardener dependabot david-dm coveralls circleci	packageName repoKey

📋 badges/semantic-release (index)

Updating README.md using merge-below-title.

• Display semantic-release badge in README.

Targets	Requires
project └─ README.md	semantic-release

📋 badges/npm-status (index)

Updating README.md using merge-below-title.

• Display npm status badge in README.

Targets	Requires	Variables
project └─ README.md	npm-published	packageName

📋 badges/npm-downloads (index)

Updating README.md using merge-below-title.

• Display npm downloads badge in README.

Targets	Requires	Variables
project └─ README.md	npm-published	packageName

📋 badges/js-gardener (index)

Updating README.md using merge-below-title.

• Display js-gardener badge in README.

Targets	Requires
project └─ README.md	js-gardener

📋 badges/dependabot (index)

Updating README.md using merge-below-title.

• Display dependabot badge in README.

Targets	Requires	Variables
project └─ README.md	dependabot	repoKey

📋 badges/david-dm (index)

Updating README.md using merge-below-title.

• Display david-dm.com badge in README.

Targets	Requires	Variables
project └─ README.md	david-dm	repoKey

📋 badges/coveralls (index)

Updating README.md using merge-below-title.

• Display coveralls badge in README.

Targets	Requires	Variables
project └─ README.md	coveralls	repoKey

📋 badges/circleci (index)

Updating README.md using merge-below-title.

• Display circleci badge in README.

Targets	Requires	Variables
project └─ README.md	circleci	repoKey

---

Requires

javascript (link)

Programming Language.

JavaScript, often abbreviated as JS, is a high-level, interpreted programming language that conforms to the ECMAScript specification. It is characterized as dynamic, weakly typed, prototype-based and multi-paradigm.

mocha (link)

JavaScript test framework.

Mocha is a JavaScript test framework for Node.js programs, featuring browser support, asynchronous testing, test coverage reports, and use of any assertion library.

chai (link)

JavaScript assertion library.

Chai is a BDD / TDD assertion library for node and the browser that can be paired with any javascript testing framework.

eslint (link)

Linting for JavaScript.

JSLint is a static code analysis tool used in software development for checking if JavaScript source code complies with coding rules.

babel (link)

JavaScript Compiler.

Babel is a toolchain that is mainly used to convert ECMAScript 2015+ code into a backwards compatible version of JavaScript in current and older browsers or environments.

semantic-release (link)

Automates npm package release workflow.

Automates the package release workflow including:

• determining the next version number
• generating the release notes
• publishing the package

npm (link)

Javascript package repository.

Requires the project to be conform with the npm standard, i.e. contain a package.json file. Does not require the project to be published to npm.

jetbrains (link)

Collection of various IDEs.

Collection of various IDEs. There exists one for every major programming language and they are all very similar (i.e. shortcuts, layout), which makes them great when switching languages.

nyc (link)

Coverage testing for javascript projects.

A major coverage testing framework for javascript. Comes with all the bells and whistles.

git (link)

Version control system.

The most used version control system. Not to be confused with github (which uses git).

circleci (link)

Run automated jobs using docker containers.

Allows set up for ci/cd using docker containers. Automates development process quickly, safely, and at scale.

gally (link)

Automation around github.com Repository Management

Allows management of github.com repositories through configuration. Very powerful when you need to synchronize settings across multiple repositories.

github (link)

Major development platform powered by git.

GitHub is a code hosting platform for collaboration and version control. Lets you and others work together on projects.

dependabot (link)

Automatic dependency updates.

Makes dependency updates very easy by automatically creating pull requests in your repo. All major programming languages are supported or work is done towards supporting them.

yarn (link)

Dependency management similar to npm.

Very similar functionality to npm cli.

coveralls (link)

Showcase and analyze coverage reports.

Enables displaying of a status badge indicated code coverage percent of the project. Furthermore allows anyone to easily drill down into missing coverage or coverage changes.

npm-published (link)

Javascript package repository published.

Requires the project to be published to npm either as a private or public package.

js-gardener (link)

NodeJs Project Management.

Enforces and helps setting up best practices around NodeJs projects. Enforces highest code quality and minimizes package setup and maintenance complexity - so you can focus on writing code. Highly recommended if you are getting started with a new package and extremely useful if you are maintaining multiple packages.

david-dm (link)

Dependency badge for javascript github repositories.

Enables displaying of a status badge indicated whether the dependencies are outdated.

---

Variables

packageName : string

Name of the package on npm.

The name of the project as published to npm. Note that for scoped packages the name can differ significantly from the repo name.

repoKey : string

Repository key.

The repository key contains the owner or organization of the project and the repository name itself, separated by a slash.

ownerName : string

Name of the owner of this project.

The owner name of the project is the name of the person or organization publishing the project under their license.

projectName : string

Name of the project.

The project name is in most cases identical to the repository name.

owner : string

The owner of the code on github.

The code owner is the gatekeeper of the project, ultimately responsible for all changes.

mergeBot : string

The github name of the bot used for automatic merging.

---

Strategies

create-only

🔹 any

Does nothing when the file is already present, otherwise creates it.

overwrite

🔹 any

Simply replace the old with the new content.

merge-deep

🔹 json, yml

Does a "smart" deep merge.

This will not work as desired for all object deep merging, but should for many cases.

merge-shallow

🔹 json, yml

Does a shallow merge aka Object.assign().

Useful when specific keys of the target need to be overwritten.

default-shallow

🔹 json, yml

Similar to merge-shallow, but keeps existing values instead of overwriting.

Useful to ensure specific keys of the target are present without overwriting existing content.

default-deep

🔹 json, yml

Similar to merge-deep, but keeps existing values instead of overwriting.

Useful to ensure specific keys of the target are present without overwriting existing content.

unique-top

🔹 list

Merges content at the top of the file and removes existing, duplicate lines.

Useful for managing e.g. .gitignore when the original content should be kept.

xml-merge

🔹 xml

Does a "smart" deep merge.

This will not work as desired for all xml merging, but should for many cases.

merge-below-title

🔹 list, nostruct

Merges content below title.