Skip to content

docs(governance): bot automation policy, inclusive language guide #1530

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RUKAYAT-CODER merged 1 commit into from
Oct 16, 2026
Merged

docs(governance): bot automation policy, inclusive language guide #1530

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions Governance/community/INCLUSIVE_LANGUAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Inclusive Language Guide

## Purpose

The words we use in code, documentation, issues, and conversation affect who feels
welcome in TeachLink Mobile. This guide says which terms the project prefers, which it
asks contributors to avoid, and how the guide is applied. It supports the expectations
in the [Code of Conduct enforcement policy](../COC_ENFORCEMENT.md) and the project's
[Values](../VALUES.md), and exists to make writing clearer as well as kinder: many of
the preferred terms are also more precise.

## Scope

This guide applies to everything contributors write in project spaces: source code
(identifiers, comments, strings, and test names), documentation, commit messages, pull
requests, issues, discussions, and release notes. It also applies to the app's own
user-facing text, which is read by teachers and children (see the
[Scope Statement](../SCOPE.md)).

It is a writing guide, not a list of banned words to be policed mechanically. Intent and
context matter, and the aim is to help people write well, not to catch them out.

## Principles

- **Be precise.** Prefer the term that says exactly what a thing is or does.
- **Describe the thing, not a person.** Avoid terms that carry a judgement about people
or groups when a neutral technical term exists.
- **Plain language.** Avoid idioms and slang that do not translate across cultures and
languages, which matters for a project with learners and contributors worldwide.
- **Assume good faith.** Correct gently, and expect to be corrected gently.

## Preferred Terms

| Instead of | Prefer | Why |
| --- | --- | --- |
| whitelist / blacklist | allowlist / denylist (or blocklist) | Names the function, not a colour |
| master / slave | primary / replica (or leader / follower, parent / child) | Removes the slavery metaphor and is more precise |
| master (branch) | `main` | The project's default branch is already `main` |
| sanity check | confidence check, quick check, validation | A "sanity" check can stigmatise mental health |
| dummy (value or data) | placeholder, sample, mock | Describes the purpose |
| grandfathered | legacy, exempt by prior approval | Avoids a term with a discriminatory origin |
| man-hours, manpower | person-hours, effort, staffing | Gender-neutral |
| guys (addressing a group) | everyone, folks, team, all | Includes everyone in the group |
| he / she (for an unknown person) | they, or rewrite in the plural | Gender-neutral |
| crazy, insane, lame, dumb (as intensifiers or insults) | surprising, unexpected, limited, unclear | Avoids using disability or mental health as an insult |
| blind spot, tone-deaf (as metaphors) | gap, oversight, unaware | Avoids metaphors built on disability |
| cripple (a feature or system) | disable, degrade, limit | Same |
| abort (for a process) | cancel, stop, exit | "Abort" is acceptable as a standard API name, see exceptions |
| hang, kill (a process) | stop, terminate, unresponsive | Acceptable as standard system terms, see exceptions |
| simple, easy, just, obviously (about a task) | omit, or describe the steps | These can make a reader feel inadequate when it is not simple for them |
| native speaker | fluent speaker | Avoids implying a hierarchy of speakers |

When writing about people, use the terms they use for themselves, and avoid referring to
a person's identity unless it is relevant.

## Terms to Avoid

Do not use, in any project space:

- slurs and demeaning terms about any group;
- terms that use a protected characteristic as an insult;
- gendered or ableist terms as jokes or intensifiers; and
- phrases that exclude or single out people, such as "you guys" to a mixed group, when a
neutral phrase would serve.

Repeated or targeted use of such language is a Code of Conduct matter, handled under the
[enforcement policy](../COC_ENFORCEMENT.md) and reported through the
[reporting process](../COC_REPORTING.md).

## Exceptions

Some uses are not changed:

- **External names.** A third-party API, protocol, file format, command, or error message
that uses a term we would avoid is quoted or called as-is. The code that wraps it
should use the preferred term for its own names where practical.
- **Standard technical terms.** Words such as `abort`, `kill`, and `hang` are established
system terms; use them where they are the standard name, and prefer neutral words in
prose.
- **Quotation.** When quoting a source, a log, or someone's words for a legitimate
reason, reproduce them accurately and note why.
- **Historical records.** Past commits, released changelogs, and archived discussions are
not rewritten.

Where an exception applies, a short comment explaining it prevents repeated questions.

## Applying This Guide

### Writing

Contributors check their own text against the table. The preferred term is a suggestion
that improves clarity, so a different clear, respectful wording is also fine.

### Review

Reviewers may suggest a change when they see a term from the "Instead of" column, using a
friendly, specific comment that names the preferred term and the reason. A suggestion is
not a block unless the term is on the list of terms to avoid, or appears in text users
will see. Authors are not asked to rewrite unrelated code only to change a term.

### Existing text

Existing occurrences are fixed **opportunistically**: when someone is already editing the
file, or in a small focused change. A repository-wide rename is not required, and is
done only as its own reviewed change so it is easy to verify. For example, a search of
`docs/` finds an occurrence of "whitelist" in `docs/TREE_SHAKING.md`, which would be
corrected the next time that document is edited.

### Enforcement

This guide is enforced by **review and conversation**, not by an automated gate. No lint
rule or CI check enforces it today. If the maintainers later add one, it must use an
allowlist of approved exceptions so that standard technical terms and external names do
not cause false failures, and it would be introduced under the
[automation policy](../policies/BOT_AUTOMATION.md).

A reviewer who is unsure how to raise a concern can ask the
[Community Manager](../roles/COMMUNITY_MANAGER.md). A person who is hurt by language in a
project space can report it through the conduct process without needing to justify it.

## Maintaining This Guide

The Community Manager and the Docs Lead maintain it. Anyone may propose an addition or a
change by opening an issue or a pull request that touches only the `Governance/` folder,
with the reason for the change. The guide is reviewed at least once a year, because
language and community norms change.

## Related Documentation

- [Code of Conduct Enforcement](../COC_ENFORCEMENT.md) and [Reporting](../COC_REPORTING.md)
- [Values](../VALUES.md)
- [Glossary](../GLOSSARY.md)
- [Community Manager role](../roles/COMMUNITY_MANAGER.md) and [Docs Lead role](../roles/DOCS_LEAD.md)
159 changes: 159 additions & 0 deletions Governance/policies/BOT_AUTOMATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
# Bot and Automation Governance Policy

## Purpose

This policy defines which automations may act on the TeachLink Mobile repository, what
permissions each may hold, and how they are reviewed and audited. A bot or workflow runs
with real credentials and acts without a person watching each step, so it is held to a
stricter standard than a person: it gets the least access that does its job, and its
access is reviewed on a schedule.

## Scope

This policy covers every non-human actor that can read, comment on, commit to, label,
merge, or release from this repository, or that holds a secret belonging to it. That
includes GitHub Actions workflows, dependency-update bots, GitHub Apps, and personal or
machine access tokens used by automation. It does not cover the tools contributors run
on their own machines.

## Allowed Automations

| Automation | What it may do | Where it is defined |
| --- | --- | --- |
| **CI and quality workflows** | Run lint, typecheck, tests, architecture and dependency checks, bundle-size and performance checks, and report results | `.github/workflows/ci.yml`, `architecture.yml`, `audit.yml`, `bundle-size.yml`, `performance-regression.yml`, `monitor-build-times.yml` |
| **Build workflows** | Build native and web artifacts | `.github/workflows/build-native.yml`, the EAS jobs in `release.yml` |
| **Release automation** | Bump the version, update the changelog, create the release, and start production builds | `.github/workflows/release.yml` |
| **Dependency updates** | Open pull requests that update dependencies, and merge a narrow class of them | `renovate.json` |

Any other automation, such as an auto-labeller, a stale-item closer, a welcome message
bot, or a merge queue helper, is **not allowed until it is added to this table** by a
pull request that follows [Adding or Changing an Automation](#adding-or-changing-an-automation).
Inactivity handling in particular stays with people, as the
[Stale Pull Request Policy](STALE_PRS.md) requires: pull requests are not closed by an
inactivity bot.

## Rules for Every Automation

1. **Least privilege.** An automation gets only the permissions it needs, for only as
long as it needs them.
2. **Named owner.** Each automation has an accountable owner (a role, not an
individual), recorded in the table in [Ownership](#ownership).
3. **No secrets in code.** Credentials live in repository or environment secrets, never
in the repository, logs, issue text, or workflow output.
4. **Never the sole reviewer.** An automation does not approve a pull request, and it does
not satisfy the human approval requirements in the
[PR Approval Requirements](APPROVAL_REQUIREMENTS.md).
5. **Identifiable.** An automation acts under a recognisable bot identity, so its actions
are distinguishable from a person's in history and audit logs.
6. **Auditable.** What it did can be traced to a workflow run, a commit, or a pull request.
7. **Failure is safe.** If an automation fails, it stops. It does not retry destructive
actions or fall back to broader credentials.

## Permissions

### Workflows

- Every workflow declares a top-level `permissions:` block and defaults to
**read-only** (`contents: read`). The existing `ci.yml` and `audit.yml` follow this
rule, which was adopted to restrict the default `GITHUB_TOKEN`.
- Write permissions are granted **per job**, never at workflow level, and only for the
scope required. For example, only the release jobs need `contents: write` and
`pull-requests: write`.
- Jobs that receive production secrets (`EXPO_TOKEN`, `MAESTRO_API_KEY`, or any signing
material) run only on trusted refs, never on pull requests from forks, and are skipped
rather than failed when the secret is absent.
- Workflows triggered by `pull_request_target`, or that check out code from a fork while
holding secrets, are **not allowed**, because they run untrusted code with trusted
access.
- Third-party actions are pinned to an immutable reference (a full commit SHA) and
reviewed before they are added. Actions that handle secrets or write to the repository
receive the most careful review.

> **Current state.** The existing workflows reference third-party actions by version
> tag (for example `softprops/action-gh-release@v2`), not by commit SHA. Pinning them is a
> follow-up owned by the Release Manager and the Security Officer; new actions are pinned
> from the date this policy is adopted.

### Dependency bot

- It may open pull requests and push to its own branches. It may not push to `main`.
- It may **automerge only** patch updates of development dependencies, and only when the
required `ci` check passes. This is the single automerge class configured in
`renovate.json`. Any widening of automerge needs maintainer approval under the process
below.
- Updates to `expo`, `react-native`, and other platform-critical packages are grouped and
reviewed by a person; the bot does not merge them.

### Release automation

- It is the only automation allowed to write to `main`: `release.yml` commits the version
bump and changelog and pushes them. This is a recorded exception to the rule that
nobody pushes directly to `main` (see the [Merge Strategy Policy](MERGE_STRATEGY.md)).
- It may create tags and releases. Tags and the commit it pushes are subject to the
signing requirements in the [Commit Signing Policy](COMMIT_SIGNING.md), and the
current gaps are tracked there.
- Store submission is gated by an explicit input and by the release sign-off in the
[Contributor and Release Sign-off Policy](CONTRIBUTOR_SIGNOFF.md); it never submits
silently.

### Tokens and Apps

- Prefer the workflow's built-in `GITHUB_TOKEN`. A personal access token is used only
when the built-in token cannot do the job, is a fine-grained token limited to this
repository, has an expiry, and is not owned by a person who may leave the project.
- A GitHub App or bot account is installed with the narrowest permission set and is
listed, with its permissions, in the register below.

## Review and Audit

| Cadence | Who | What |
| --- | --- | --- |
| On every change to a workflow or bot config | A [Maintainer](../roles/MAINTAINER.md) and the [Security Officer](../roles/SECURITY_OFFICER.md) | Review permissions, secrets used, triggers, and new third-party actions |
| Monthly, in the governance review | Maintainers | Check the register against the installed Apps, tokens, and workflows; confirm no unlisted automation exists |
| Quarterly | Security Officer | Review the secrets and tokens held by automation, rotate any that are old or unused, and revoke any that are no longer needed |
| After any incident | Security Officer | Review what the automation could reach; reduce access where the incident showed it was too broad |

A review records its outcome, including "no change needed". A permission that has not
been used in a review period is removed.

## Adding or Changing an Automation

1. Open an issue describing the automation, why it is needed, what it does, the exact
permissions and secrets it needs, and what happens if it malfunctions.
2. Propose the change in a pull request that updates this policy's tables and the
workflow or configuration together.
3. The Security Officer and a Maintainer review it. An automation that writes to the
repository, holds a secret, or can merge needs both to approve.
4. After merge, the owner adds it to the register and confirms the permissions in the
live configuration match the approved ones.

## Incidents

If an automation is compromised, misbehaves, or acts outside its remit:

1. The Security Officer or any Maintainer disables it immediately (disable the workflow,
uninstall the App, or revoke the token).
2. Credentials it held are rotated under the Security Officer.
3. The actions it took are reviewed and reverted where necessary.
4. The cause is recorded and handled under the [Security Policy](../SECURITY_POLICY.md)
and the [Escalation Path](../processes/ESCALATION_PATH.md).

## Ownership

| Automation | Accountable role |
| --- | --- |
| CI and quality workflows | Maintainers |
| Build workflows | [Release Manager](../roles/RELEASE_MANAGER.md) |
| Release automation | Release Manager, with the Security Officer for credentials |
| Dependency bot | Maintainers |

This policy is owned by the Maintainers. Changes are proposed in a pull request that
touches only the `Governance/` folder.

## Related Documentation

- [PR Approval Requirements](APPROVAL_REQUIREMENTS.md)
- [Merge Strategy Policy](MERGE_STRATEGY.md) and [Commit Signing Policy](COMMIT_SIGNING.md)
- [Stale Pull Request Policy](STALE_PRS.md)
- [Security Policy](../SECURITY_POLICY.md)
- [Security Officer role](../roles/SECURITY_OFFICER.md)
Loading