minimal rulesets

README.md

rulesets

minimal best practices

• branch & release protection
• github flow with linear, conventional commits
• codeQL merge protection

requires zero maintenance & setup¹

Install

Download ZIP

add documents

add a contribution guide & security policy.²

Head to repository main page:

• Above the list of files
• Select Add file > Create new file

For each document:

• Add name and contents.
• Click Commit Changes
• copy paste each documents commit msg field
  into the commit message field in form.
• Select Commit Changes

add the following:

A contribution guide

• file name: .github/CONTRIBUTING.md
• contents : CONTRIBUTING.md content
• commit msg: docs: added contribution guide

A security policy

• file name : .github/SECURITY.md
• contents : SECURITY.md content
• commit msg: docs: added security policy

import rulesets

• Head to Settings > Rules > Rulesets
• Select New Ruleset > Import a ruleset
• Import each <ruleset>.json included here.

enable security features

private vulnerability reporting

• Head to Settings > Code Security > Private vulnerability reporting
• Select Enable

default codeQL

must use default setup, not workflow

• Head to Settings > Code Security > Code Analysis
• Select Tools:CodeQL > Setup > Default
• Select Enable/Submit w/o changing anything

license

MIT-0 No Attribution

Copyright 2O24  
Nicholas Kyriakides, @nicholaswmin

This work (entire project, repository or all files in "gist")  
is licensed under the terms of the MIT-0 license.   
For a copy, see <https://opensource.org/licenses/MIT-0>.

notes

inspired by dziuba: who needs process? (2011) & ossf:scorecard

Footnotes

1. rules that might need a code/dependency update in the future or require any form of collaborator setup are excluded.
   *allowed: CodeQL but only when using the default setup, since its configuration is automatically managed by Github.
   *excluded: any rules relying on custom workflows, their versioned @actions/checkout-v<x> steps require updates.
   *excluded: signed-commits require local setup ↩

2. required documentation like LICENSE are out of scope of this guide but assumed to exist and correctly configured. ↩

codeql-default.json

{
  "name": "CodeQL-merge",
  "target": "branch",
  "source_type": "Repository",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": [
        "~DEFAULT_BRANCH"
      ]
    }
  },
  "rules": [
    {
      "type": "code_scanning",
      "parameters": {
        "code_scanning_tools": [
          {
            "tool": "CodeQL",
            "security_alerts_threshold": "high_or_higher",
            "alerts_threshold": "errors"
          }
        ]
      }
    }
  ],
  "bypass_actors": []
}

CONTRIBUTING.md

Contributions

The key words must, must not, required, shall, shall not
should, should not, recommended, may, and optional in this
document are to be interpreted as described in RFC 2119.

• The runtime, source code & Github defaults are the only 1st-class citizens.
  Anything else, including process & conventions are undesirable dependencies.
• Dependencies should be lightweight, familiar to use & well-defined.
• A robust & well-defined test suite is more valuable than the code.
• Conciseness over verbosity. You don't need it.

Publishing

created as Github Release & follow SemVer:

example: publishing a new release:

gh release create v1.7.1

List current releases:

gh release list

note: versions must use format: vX.X.X.

Branching

follow Github Flow:

1. Create a branch
   Use a concise name, i.e: increase-test-timeout
2. Push code changes to the branch
   Commit messages must follow conventions
3. Create a pull request
4. Address review comments
5. When approved, merge the PR & delete the branch .

note: default/main branch must always exist in a working & deployable state.

Commit messages

follow Conventional Commits v1, requiring a format:

<type> <description>

• <type> must be any of: fix: or feat: or specific others.
• <description> must be a short summary of code changes.

examples:

# good:
git commit -m"fix: array parsing issue with multiple spaces"

# bad: "Feat." is invalid. Use "feat:" or "fix:"
# bad: no space between keywords.
git commit -m"Feat.users can reset their password"

note: breaking changes must consult the specification,
which also includes additional, more specific formats.

linear-conventional-commits.json

{
  "name": "Linear & Conventional Commits",
  "target": "branch",
  "source_type": "Repository",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": [
        "~ALL"
      ]
    }
  },
  "rules": [
    {
      "type": "required_linear_history"
    },
    {
      "type": "commit_message_pattern",
      "parameters": {
        "name": "Conventional Commits v1 format",
        "negate": false,
        "pattern": "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\\([\\w\\-\\.]+\\))?(!)?: ([\\w ])+([\\s\\S]*)",
        "operator": "regex"
      }
    }
  ],
  "bypass_actors": []
}

protected-github-flow.json

{
  "name": "Protected default & Github Flow",
  "target": "branch",
  "source_type": "Repository",
  "enforcement": "active",
  "conditions": {
    "ref_name": {
      "exclude": [],
      "include": [
        "~DEFAULT_BRANCH"
      ]
    }
  },
  "rules": [
    {
      "type": "deletion"
    },
    {
      "type": "pull_request",
      "parameters": {
        "required_approving_review_count": 0,
        "dismiss_stale_reviews_on_push": true,
        "require_code_owner_review": false,
        "require_last_push_approval": false,
        "required_review_thread_resolution": false
      }
    },
    {
      "type": "non_fast_forward"
    }
  ],
  "bypass_actors": []
}

protected-release.json

{
  "name": "Protected Releases",
  "target": "tag",
  "source_type": "Repository",
  "enforcement": "active",
  "conditions": {
    "repository_name": {
      "exclude": [],
      "include": [
        "~ALL"
      ]
    },
    "ref_name": {
      "exclude": [],
      "include": [
        "~ALL"
      ]
    }
  },
  "rules": [
    {
      "type": "deletion"
    },
    {
      "type": "non_fast_forward"
    }
  ]
}

SECURITY.md

Security Policy

The authors take security issues seriously.
We appreciate your efforts to responsibly disclose your findings

Report vulnerabilities

From the repository homepage, visit:

• Visit Security Tab > Reported Advisories > New Security Advisory
• Fill-in the form.
• Select Create (draft) security advisory

The authors will:

• send a response with the next steps on handling your report
• keep you informed of the progress towards a fix & announcement
• possibly ask for additional information

Note: 3rd-party module issues should be reported to their own maintainers

Guidelines

contributors should abide by these guidelines,
at the very least on a best-effort basis.

Github Docs: Code Security

• Quickstart for Repositories

OSSF: Open Source Security Foundation

• Best Practices Guide: npm
• Concise Guide for Developing Open Source Software
• Concise Guide for Evaluating Open Source Software
• Build Provenance

Tooling

should run a:

• CodeQL code-scan merge protection
  threshold:: High
alert: Errors