This document outlines the configuration of this repo as well as the basic

process we use to manage the project. As Github has matured as a platform

and HTML5 Boilerplate has matured as a project there are a lot of lessons

to be learned from the way we run the show here.

This section will go through the way we configure the repo in GitHub.

Open source projects get the full power of the platform and as a project

we like to experiment with new GitHub features. Our current configuration

might help you figure out some things you want to do in your own projects.

This section outlines the basic configuration options we use.

* We have a stub of a Wiki still, so we have wikis turned on. The most

interesting page that remains is a history of the project written several

years ago.

* We use the Issues feature heavily. We don't yet have Issue Templates set

up, but we do have adding them as an issue, so we'll take advantage of them

at some point.

* Discussions are enabled, but they haven't been very useful so far.

The most visible portion of our configuration is the way we handle pull

requests. At the most basic level, we require pull requests to add code

to the repo and require a review to merge code. In addition we run several

code quality checks on every pull request to make sure we're not introducing

anything we don't want into the codebase.

We take advantage of the "draft" feature for PRs. This way we have visibility

throughout the life of the PR.

Let's take a look at how we configure our `main` branch.

`main` is the default branch and is our only protected branch. We use feature

branches to add features and/or fix issues in the codebase. Other project

configurations might require a long-running, similarly protected, `development`

branch but for us the single protected `main` branch is enough for our

purposes.

Our branch protection rules are as follows:

* We require a pull request (PR) with one approving reviewer to merge code

* In addition to the PR and approving reviewer, we require three status checks

to pass before code can be merged

* Build with Node 16

* Build with Node 14

* LGTM analysis: JavaScript

* We *allow* force pushes for project admins. While force pushes can create

some head scratching moments for people who have cloned the repo and update

before and after the force push, the ability to clean up the `HEAD` of a

public branch like this in an emergency is useful.

* We run a simple *build status* check. This is the most basic test you can run

and is absolutely vital. If you can't build your project you're in trouble.

Currently we're testing against Node 14 and 16.

* We take advantage of our access to *CodeQL analysis* Free for research and

open source don't you know :) We don't have a ton of surface area to cover,

but it's nice to have this powerful code scanning tool available to us.

* We run a *dependency review* scan to see if any newly added dependencies add

known security flaws. This is important for even us, but for a project that

uses a larger number of third party dependencies, this sort of check is vital.

* Since we're fan of the "belt and suspenders" approach to security, we also

run a *LGTM.com* scan as well as the CodeQL scans. This tool, built on top of

CodeQl can shake out different issues so it's nice to have the pair.

* We push any changes to `main` to our [HTML5\-Boilerplate Template Repo](https://github.com/h5bp/html5-boilerplate-template)

Since we've talked about some of our Actions, let's look at the full configuration

of our `.github` folder.

* workflows

* `build-dist.yaml` is currently broken. We can't push to `main` without a

code review, so this task is blocked. What I would like, (are you there,

GitHub, it's me, Rob) is to allow Actions to bypass branch protection

rules. I think we'll have to basically write a mini-bot that opens a PR

whenever there are changes to `main` and then pushes to the same branch

until the PR is closed. In some ways that will be better as it will be less

noisy in terms of bot pushes to main.

* `codeql-analysis.yml` controls our CodeQL action. We use the defaults. If

you're building something with more JAvaScript footprint, you can tweak

the settings for this job.

* `dependency-review.yml` does what it says on the tin- it tests newly

introduced dependencies for vulnerabilities.

* `publish.yaml` is the action that publishes all the various versions of

the project. When we create a new tag and push it to GitHub, this script

publishes our npm package and creates a GitHub release and attaches a zip

file of our `dist` folder.

* `push-to-template.yaml` pushes the `HEAD` of `main` to our template repo

* `spellcheck.yml` automatically checks markdown files for typos with cSpell.

* `test.yaml` runs our test suite.

* `CODE_OF_CONDUCT.md` is our Code of Conduct, based on

[Contributor Covenant.](https://www.contributor-covenant.org/)

* `CONTRIBUTING.md` contains our contribution guidelines.

* `ISSUE_TEMPLATE.md`is our new issue boilerplate.

* `PULL_REQUEST_TEMPLATE.md`is our new PR boilerplate.

* `SUPPORT.md`points people to different (non-HTML5-Boilerplate) support

resources

* `dependabot.yml`is our Dependabot configuration. We do `npm`, monthly on

two separate `package.json` files, one in `src` and one in project root.

That covers most of the interesting GitHub features and functionality that we

use. We're going to continue to keep this document up to date as we change

things or new GitHub features.