Standards
- Behavioral standards
- Operational standards
- Project Standards
- Licenses
- Naming conventions
- Administrative tasks

Standards

These standards represent the way of working of the BNA Mechanics team.

They aim to create an enjoyable contributing culture, while making it obvious and natural to build high quality deliverables.

Behavioral standards

Culture & Values

Collaboration

Operational standards

Data-driven

Automation

Documentation

Error Handling as a First-Class Citizen

Project Standards

General recommendations

Continuous Integration

The CI rules:

The PeopleForBikes/.github repository contains starter workflows that should be used when creating a project.

Required tasks

SCM

Testing

Licenses

The BNA Mechanics team selected the following licenses to use depending on the type of work being done:

Software

Default: MIT

For most substantial BNA Mechanics open source software projects, there's a simple default answer: MIT.

MIT is the most popular license for public open source projects on github. It has great cultural acceptance and is simple to understand, use, and comply with:

If you feel that MIT is really the wrong license for a substantial BNA Mechanics open source project, let's talk with the team.

Content

Default: CC-BY-4.0

Occasionally we publish substantial non-software content (e.g., documentation, media) that we want to give others permission to copy, modify, and distribute if they give us credit and don't use our trademarks. That's what CC-BY-4.0 allows. It's roughly equivalent to MIT in terms of being permissive and having good cultural acceptance, but is designed for non-software works (e.g., license notice can be provided with a link rather than including a copy of the license text).

To use CC-BY-4.0:

If you feel that CC-BY-4.0 is really the wrong license for substantial GitHub open source non-software content, let's talk with the team.

Non-substantial works

Default: CC0-1.0

MIT and CC-BY-4.0 conditions are easy to comply with, but sometimes projects are better served by not having any conditions, not even a requirement for attribution.

CC0-1.0 waives all copyright restrictions but reserves trademark and patent rights, making it an easy unconditional license for PeopleForBikes material when:

Examples

  1. Sample snippets; eg those under https://developer.github.com/guides/
  2. Starter or other boilerplate material
  3. Purely functional configuration with minimal expressivity that we don't think is/ought be subject to copyright anyway; add certainty that there are no restrictions
  4. Data in which there is clearly no demonstrable business value from mandating maintenance of copyright notices
  5. More substantial code/material alongside/in same repo as one of the above and still no demonstrable business value from restrictions; just use an unconditional license for more substantial bits to minimize number of licenses involved

To use CC0-1.0:

Have questions about whether what you're working on matches one of the above example classes and meets the two criteria above, or feel that CC0-1.0 isn't the right license for those cases? Let's talk with the team.

Naming conventions

Versioning

Visual assets

Visual assets should be named in a way where contributors can easily extract the relevant information directly from the file name itself. There must not be any complicated nested folder structure necessary.

Examples

Administrative tasks

We recommend using the GitHub CLI in general as we find it very convenient, but even if it is not your cup of tea, it should at least be used to create new repositories with the right parameters from the get go.

All the operations can also be performed via the GitHub website.

Remark: these operations require administrator privileges.

Create a new GitHub repository

Start by defining the PFB variables:

export PFB_REPO=my-project
export PFB_REPO_DESCRIPTION="Describe my project in one line."
export PFB_REPO_LANG=<Node,Python,Rust> # Choose the appropriate language

Then, depending of the type of project being created, the bootstrap process varies.

Bootstrap a NextJS project

Create the NextJS app:

npx create-next-app@latest \
  --app \
  --ts \
  --eslint \
  --src-dir \
  --import-alias @/* \
  --use-pnpm \
  --no-tailwind \
  "${PFB_REPO}"

Import the BNA mechanics files:

cd ${PFB_REPO}
TEMPLATE_GITHUB_TMP="$(mktemp -d)/template"
git clone --depth=1 git@github.com:PeopleForBikes/bna-mechanics-project-template "${TEMPLATE_GITHUB_TMP}"
rsync -vrlp --exclude '.git' "${TEMPLATE_GITHUB_TMP}/" .
echo -e "# ${PFB_REPO}\n\n${PFB_REPO_DESCRIPTION}" > README.md

Check the .github/workflows folder and remove the workflows that do not belong to the project.

git add .
git commit -sam "Import BNA Mechanics files" \
  -m "Imports the BNA Mechanics files from the project template."

Configure the GitHub CLI to use SSH:

gh config set git_protocol ssh -h github.com

Create the GitHub repository:

gh repo create \
  "PeopleForBikes/${PFB_REPO}" \
  --public \
  --description "${PFB_REPO_DESCRIPTION}" \
  --source=. \
  --remote=upstream \
  --push

Bootstrap a Rust/Python project

Create the GitHub repository:

gh repo create \
  "PeopleForBikes/${PFB_REPO}" \
  --public \
  --template "PeopleForBikes/bna-mechanics-project-template" \
  --description "${PFB_REPO_DESCRIPTION}"
git clone "git@github.com:PeopleForBikes/${PFB_REPO}"

Initialize the project, depending on the programming language:

Add a README.md and the appropriate .gitignore file:

cd "${PFB_REPO}"
echo -e "# ${PFB_REPO}\n\n${PFB_REPO_DESCRIPTION}" > README.md
curl https://raw.githubusercontent.com/github/gitignore/main/${PFB_REPO_LANG}.gitignore \
  | sort -u \
  | grep -v -e "^#" \
  | grep -v -e "^$" \
  > .gitignore

Then submit the changes:

git add .
git commit -sam "Initial import" -m "Imports project scaffolding."
git push

All projects

Check the .github/workflows folder and remove the workflows that do not belong to the project.

Apply the labels with labelr:

labelr --organization PeopleForBikes --sync .github/labels.yml

Finally, setup the branch protection:

The checks may need to be adjusted based on the language that was selected for the project.

echo '{
  "required_status_checks": {
    "strict": true,
    "checks": [{ "context": "ci-rust / lint"}, {"context": "ci-rust / test"}, {"context": "ci-rust / build"}]
  },
  "enforce_admins": false,
  "required_pull_request_reviews": {
    "dismiss_stale_reviews": true,
    "required_approving_review_count": 1
  },
  "restrictions": null
}' >/tmp/config-branch-rules

gh api \
  --method PUT \
  --preview luke-cage \
  --input /tmp/config-branch-rules \
  repos/PeopleForBikes/${PFB_REPO}/branches/main/protection

As the final touch, some repository settings can also be adjusted:

gh repo edit --enable-merge-commit=false --delete-branch-on-merge

Archive a public repository

Archive repositories to indicate that they are unmaintained and make them read-only.

Start by editing the repository's README.md file to add the following note at the top:

> **NOTE**: _This repository is no longer supported or updated by the BNA
> Mechanics team. If you wish to continue to develop this code yourself, we
> recommend you fork it._

Close all open issues and pull requests and archive the repository:

for n in $(gh issue list --state open --json number --jq .[].number); do gh issue close ${n} --reason "This repository was archived."; done
for n in $(gh pr list --state open --json number --jq .[].number); do gh pr close ${n} --comment "This repository was archived."; done
gh repo archive -y