conventions

WIP
Create repositories with pluggable conventions
End goals is to match scorecard checks in a plug/play manner.

• Overview
  • A convention
  • Example A: Base convention
  • Example B: Semver convention
  • Example C: Conventional Commits convention
  • Example D: unit-testing convention
  • Example E: Whatever convention
• Usage
• Flow
• Notes
• Todo

Overview

A CLI app that uses the Github API to create repositories.

The repositories are described as a list of pluggable, user-definable conventions.

example: A base plus 4 different conventions:

├─ conventions/
   ├─ base/
   ├─ unit-testing/
   ├─ conventional-commits/
   ├─ semver/
   ├─ github-flow/

A convention

A convention is a self-contained folder describing a general convention,
for example: Conventional Commits.

It's a partial repository structure with all the necessary
documents and files to support the convention:

Each convention self-contains all the necessary:

• Documents
  • README.md
  • guides
  • policies
  • etc
• rulesets
• workflows
• configurations
• etc.

to add that convention to the repository.

The base convention

The base convention builds the minimally-working "skeleton" repository, hence it's always required:

base
├── .github
│   ├── CONTRIBUTING.md
│   └── SECURITY.md
├── rulesets
│   └── protected-branch.json
├── src
│   └── index.js
├── README.md
└── package.json

Example B: Semver convention

adds:

• a workflow to publish to npm automatically
• a ruleset to restrict tag versioning to semver formatting
• a CONTRIBUTING section to explain this convention

semver
├── .github
│   ├── CONTRIBUTING.md
│   └── workflows
│       └── npm-publish.yml
└── rulesets
    └── semantic-tags.json

Example C: Conventional Commits convention

adds:

• a ruleset to restrict commit messages to follow the prescribed format
• a CONTRIBUTING section to explain this convention

conventional-commmits
├── .github
│   └── CONTRIBUTING.md
└── rulesets
    └── conventional-commits.json

Example D: unit-testing convention

adds:

• a test folder and a basic.test.js unit-test.
• a package.json that adds a line:

"scripts": {
  "test": "node --test"
}

adds:

• a workflow to run the unit tests on CI.
• a ruleset to restrict merge of PRs only if unit-tests pass.
• a CONTRIBUTING section to explain this convention

unit-testing
├── .github
│   ├── workflows
│   │   └── test.yml
│   └── CONTRIBUTING.md    
├── test
│   └── basic.test.js
├── rulesets
│   └── pr-status-checks.json
├── README.md
└── package.json

Example E: whatever convention

Conventions are user-definable so anything goes.

Usage

Run this CLI app and point to a conventions folder:

node --run new --conventions=./conventions

which should produce this repository:

my-repo
├── .github
│   ├── workflows
│   │   ├── npm-publish.yml
│   │   └── test.yml
│   ├── CONTRIBUTING.md    
│   └── SECURITY.md    
├── test
│   └── basic.test.js
├── rulesets
│   ├── protected-branch.json
│   ├── conventional-commits.json
│   ├── pr-status-checks.json
│   └── semantic-tags.json
├── README.md
└── package.json

This repository now supports the following conventions/practices:

• Semver:

  • a workflow to publish.yml to npm
  • rulesets so tags can only use semantic versioning tag numbers
  • sections in CONTRIBUTING detailing this convention

• Conventional Commits:

  • rulesets so commits can only use conventional commit message formats
  • sections in CONTRIBUTING detailing this convention

• Unit tests:

  • Basic unit-tests runnable via node --run test
  • unit-tests that run on CI via a test.yml workflow
  • rulesets that require unit-tests passing before merge.
  • sections in CONTRIBUTING & README detailing this convention

Flow

• Some files are merged by section, i.e markdown documents such as README.
• Other files are merged by property, i.e package.json
• Other files are left-intact and added side-by-side in the same folder, i.e ruleset.json, workflows.yml etc

Notes

• Github API extensions are in: ./extensions
• The base convention is base
• Conventions can be ordered by prefixing their filename with a number:
  • i.e: 1-conventional-commits, 2-github-flow, etc...

Documents:

Badges

Badges can be added by enclosing them as a codeblock with lang:badge.
Badges get repositioned to the top of the page.

```badge
badge-goes-here
```

example:

```badge
![Static Badge][badgeurl]
```

don't forget to add the link somehere in the doc.

[badgeurl]: https://img.shields.io/badge/foo-bar?label=foobar)

Todo

• Add tests
• Merge Document
  • Has issues (dupe sections), rethink it
  • Allow sectional updates (badges etc)
• Merge JSON
• Github Repo Settings, how to deal with?
• Generic files, what happens on conflict/merge, i.e: images?
• Use the --dir params to point to a conventions folder.
• Fix rulesets (waiting for Github support reply)
• Test no reflink links (inline)
• Fix TOC markdown updates (delete it and recreate it?)
• Tokens should be extended into appropriate types:
  • i.e: NpmVersionToken extends Token which validates an npm version string
• Use autocomplete prompt for license (allow UNLICENSED)
• Fix tokenizer review
• !important: Each convention should have its own tokens
• Allow preanswering questions via CLI args
• Ditch some composed tokens for complex prompts. i.e: token author-url can be removed; then simply have author return an object with name and url.
• Fix the unfinished src/tokenizer/validator.test.js

Test

node --run test

important: tests must be run with NODE_ENV=test

Authors

@nicholaswmin

License

The MIT License