diff --git a/docs/about-this-repo.md b/docs/about-this-repo.md new file mode 100644 index 00000000..ac36a96a --- /dev/null +++ b/docs/about-this-repo.md @@ -0,0 +1,117 @@ +# About This Repo + +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. + +## GitHub configuration + +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. + +### General Configuration + +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. + +### Pull Requests + +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` + +`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. + +#### GitHub Actions and Other Checks That Run on `main` + +* 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. + +### .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.