/conventions

repository configurator [WIP]

Primary LanguageJavaScriptMIT LicenseMIT

conventions

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

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:

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