Skip to content

Add community review etiquette, inclusive language, events, and social media policies #1910

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 17, 2026
Merged

Add community review etiquette, inclusive language, events, and social media policies #1910

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
93 changes: 93 additions & 0 deletions Governance/community/EVENTS_POLICY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Community Events Policy

| Field | Value |
| --- | --- |
| Document | `Governance/community/EVENTS_POLICY.md` |
| Status | Active |
| Version | 1.0.0 |
| Owner | Maintainer Team |
| Last reviewed | 2026-10-17 |
| Review cadence | Every 6 months |
| Applies to | Any event, meetup, workshop, livestream, or hackathon that is held in the project's name or with project resources |
| Related | [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) · [`community/SPONSORSHIP.md`](SPONSORSHIP.md) · [`community/MEDIA_POLICY.md`](MEDIA_POLICY.md) |

This policy describes how community events are proposed, approved, run, and
sponsored. It applies to online and in-person events, whether hosted by a
maintainer, a contributor, or an external partner using the project's name.

## 1. What counts as a project event

An event is "in the project's name" if it is advertised as a TeachLink event,
uses the project's name or marks, is funded by the project or its treasury, or is
run by a maintainer acting in their project role. A private gathering among
contributors, without project branding or funds, is not a project event and does
not need approval.

## 2. Proposing an event

1. **Open an issue** using the community label and describe:
- the event's purpose and audience;
- the format, date, time zone, and expected size;
- the organiser and any co-organisers;
- the budget and where the funds would come from;
- any sponsors and what they receive in return.
2. **Include a rough run-of-show** (duration, sessions, and who leads each) and
the channel where attendees will be asked to follow the Code of Conduct.
3. **Allow time.** Proposals should be opened at least **14 days** before an
online event and **30 days** before an in-person event so maintainers can
review budget and logistics without rushing.
4. **Name a single accountable organiser.** That person is the contact for
conduct issues during the event.

## 3. Approval

- A maintainer (see [`roles/MAINTAINER.md`](../roles/MAINTAINER.md)) approves the
event and records the decision on the issue.
- Events that spend treasury funds or sign a sponsorship also follow
[`community/SPONSORSHIP.md`](SPONSORSHIP.md) and the treasurer's review.
- If the organiser is also the approving maintainer, a second maintainer must
approve, so no one approves their own spend.
- Approval is for a specific event; recurring events are re-approved at least
once per quarter.

## 4. Code of Conduct applicability

- The [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) applies to every project
event, online and in person, including side chats and socials.
- The event page, invitations, and any pre-event communication must link the Code
of Conduct and state how to reach the organiser privately.
- The organiser (or a named delegate) must be reachable for the whole event and
must be able to act on a report, including removing a participant.
- For in-person events, publish what the escalation path will be on the day; for
online events, state which private channel a report may use. See
[`processes/ESCALATION_PATH.md`](../processes/ESCALATION_PATH.md).
- A report is handled under [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) and
[`policies/MODERATION.md`](../policies/MODERATION.md); the organiser does not
decide the outcome alone.

## 5. Sponsorship and funds

- Any sponsor, in-kind or cash, must be disclosed on the event issue before the
event is announced.
- Sponsored events must not give a sponsor editorial control over talks,
speakers, or the Code of Conduct.
- Sponsors that conflict with the project's values or that are under sanctions
screening (see [`compliance/SANCTIONS.md`](../compliance/SANCTIONS.md)) are not
accepted.
- A post-event note is posted on the issue: attendance, a short summary, and how
funds were spent. Transparency is the default, not an extra.

## 6. After the event

- The organiser posts a short debrief on the issue within **7 days**, including
any conduct reports (without personal detail) and lessons learned.
- Recorded material, if published, follows
[`community/MEDIA_POLICY.md`](MEDIA_POLICY.md).
- Funded events that do not happen are cancelled on the issue and any committed
funds are returned to the treasury.

## 7. Change log

| Date | Version | Change |
| --- | --- | --- |
| 2026-10-17 | 1.0.0 | Initial release. |
83 changes: 83 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,83 @@
# Inclusive Language Guide

| Field | Value |
| --- | --- |
| Document | `Governance/community/INCLUSIVE_LANGUAGE.md` |
| Status | Active |
| Version | 1.0.0 |
| Owner | Maintainer Team |
| Last reviewed | 2026-10-17 |
| Review cadence | Every 6 months |
| Applies to | All code, comments, documentation, commit messages, issues, pull requests, and community channels in `rinafcode/teachLink_backend` |
| Related | [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) · [`policies/COMMUNICATION_NORMS.md`](../policies/COMMUNICATION_NORMS.md) |

This guide records the language the project prefers and the language it avoids.
It exists so that everyone — regardless of background, first language, or
experience — can read our code and discussion without being excluded by an
avoidable word. It is a style guide, not a spelling test, and it is not a trap.

## 1. Preferred terms

Use terms that describe **what a thing does**, not a metaphor borrowed from
history, violence, or a person's identity.

| Prefer | Because |
| --- | --- |
| `primary` / `replica` | Describes the role in replication without a master/slave hierarchy. |
| `allowlist` / `denylist` | States the function directly. |
| `blocklist` (for content) | States the function directly. |
| `parent` / `child` (or `upstream` / `downstream`) | Describes the relationship. |
| `placeholder` / `dummy` (for a stand-in value) | Describes the value. |
| `main` / `default branch` | The repository's actual branch names. |
| `they` / `folks` / `everyone` | Gender-neutral and accurate for a mixed group. |
| `sanitize` / `normalize` / `validate` | Describes the transformation precisely. |
| `assets-person`, `contributor`, `maintainer` | Describes the role, not the person's identity. |

## 2. Terms to avoid

The following words are not permitted in new code, comments, documentation, or
community discussion. Where they already exist, replace them when you touch the
surrounding file rather than in a standalone rename-only change.

| Avoid | Use instead | Why |
| --- | --- | --- |
| `master` (branch or node) | `main`, `primary`, `replica` | Carries a master/slave connotation. |
| `slave` (node or process) | `replica`, `secondary`, `worker` | Carries a dehumanising connotation. |
| `whitelist` / `blacklist` | `allowlist` / `denylist` | Ties value to colour and race. |
| `blacklist` / `blackhole` (verb) | `block`, `drop`, `discard` | As above. |
| `dummy` (as an insult) | `placeholder`, `stub`, `sample` | Derogatory when aimed at a person. |
| `crazy`, `insane`, `psycho` | `unexpected`, `surprising`, `fragile` | Trivialises mental illness. |
| `crippled`, `lame` | `disabled`, `slow`, `underpowered` | Ableist. |
| `grandfathered` | `legacy`, `pre-existing`, `exempted` | Ties exemption to a voting-rights history. |
| `man hours` / `manpower` | `person-hours`, `staffing`, `effort` | Gendered. |
| `guys` (mixed group) | `folks`, `everyone`, `contributors` | Gendered when the group is mixed. |
| `he` / `she` (default pronoun) | `they` | Erases non-binary people. |
| Gendered or sexualised terms of address | The person's name or role | Harassment risk. |

This list is intentionally short. It covers the terms most likely to appear in a
backend repository; it is not an exhaustive dictionary.

## 3. Enforcing it

- **By default, gently and in the thread.** A reviewer flags an avoidable term
with a `nit:` prefix and the preferred alternative; the author fixes it before
merge. Most cases end there.
- **In code review, it is a blocking `nit:` only when the term is in the diff.**
We do not require a contributor to rename unrelated pre-existing code in the
same change.
- **Automation is welcome.** Where a term can be caught mechanically (an API
field, a metric name, a constant), prefer a lint rule or a test over a
reviewer's memory. Propose the rule in a follow-up issue.
- **Never weaponise this guide.** It is not a basis for policing accents, grammar,
or a contributor's English. Intent and clarity come first; a good-faith
wording slip is corrected, not punished.
- **Persistent bad-faith use** — slurs, harassment, or deliberately demeaning
language — is a conduct matter and is handled under
[`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) and
[`policies/MODERATION.md`](../policies/MODERATION.md), not by this guide.

## 4. Change log

| Date | Version | Change |
| --- | --- | --- |
| 2026-10-17 | 1.0.0 | Initial release. |
99 changes: 99 additions & 0 deletions Governance/community/REVIEW_ETIQUETTE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
# Review Etiquette

| Field | Value |
| --- | --- |
| Document | `Governance/community/REVIEW_ETIQUETTE.md` |
| Status | Active |
| Version | 1.0.0 |
| Owner | Maintainer Team |
| Last reviewed | 2026-10-17 |
| Review cadence | Every 6 months |
| Applies to | Everyone who opens, reviews, or comments on a pull request in `rinafcode/teachLink_backend` |
| Related | [`CONTRIBUTING.md`](../../CONTRIBUTING.md) §9 · [`policies/COMMUNICATION_NORMS.md`](../policies/COMMUNICATION_NORMS.md) · [`policies/REVIEW_POLICY.md`](../policies/REVIEW_POLICY.md) |

This document describes the tone and expectations for code review in this
repository. It complements the reviewer duties in `CONTRIBUTING.md` §9 and the
communication norms in [`policies/COMMUNICATION_NORMS.md`](../policies/COMMUNICATION_NORMS.md);
where the two overlap, `CONTRIBUTING.md` wins. It adds no new merge gate.

## 1. Why review etiquette matters

Review is the main way we transfer context between contributors. On a large
NestJS backend a hurried or hostile review costs more than it saves: authors hide
mistakes, reviewers skim, and the same defect is discovered twice. The goal of
every review is a **better change and a better-informed author**, not a verdict
on the author.

## 2. Tone and expectations

- **Critique the change, not the person.** Say "this query is unbounded" rather
than "you always write unbounded queries".
- **Assume good faith and missing context.** Ask before concluding intent: "did
you consider the pagination path?" beats "this ignores pagination".
- **Be specific and actionable.** Point at the file and line, name the problem,
and, where you can, suggest a path forward.
- **Separate blocking from non-blocking** by prefixing comments with `nit:`,
`optional:`, or `question:`. An author should never have to guess what must
change before merge.
- **Praise what is right.** A short "nice, this fixes the race" is cheap and
keeps the review honest.
- **No sarcasm, no pile-ons.** Once a reviewer has raised a point, others add
signal, not volume.
- **Keep the record public.** Review comments belong on the pull request so the
reasoning is searchable later.

## 3. Author norms

1. **Link an issue.** Every pull request links the issue it resolves
(`CONTRIBUTING.md` §2); reviews start from that context.
2. **Make the diff readable.** Keep the change scoped to the issue. Unrelated
refactors belong in a separate pull request.
3. **Describe intent.** A short summary — what changed, why, how it was verified
— lets a reviewer load the change into their head faster.
4. **Respond to every comment.** Either apply the change or explain, with
reasoning, why not. A silent thread blocks the review.
5. **Do not force-push during review.** Add commits so reviewers can see the
delta; expect approvals to be invalidated by new commits (`CONTRIBUTING.md`
§9).
6. **Do not resolve your own review threads.** Reviewers resolve; authors answer.
7. **Thank the reviewer.** It costs nothing and encourages thorough review.

## 4. Reviewer norms

1. **Review the change, not a rewrite.** Judge whether the change is correct,
safe, and appropriately scoped — not whether you would have written it
differently.
2. **Do one thorough pass.** A second round should be reserved for genuinely
substantive changes, not for style points the tooling already decides.
3. **State the condition for approval.** If a change is close, say exactly what
would make it mergable; do not leave the author guessing.
4. **Distinguish blocking from optional.** Use the `nit:` / `optional:` / `question:`
prefixes from §2.
5. **Review within the review SLA** in [`policies/REVIEW_SLA.md`](../policies/REVIEW_SLA.md)
and `CONTRIBUTING.md` §9, or say when you will.
6. **Recuse when conflicted.** If you are not able to judge the change fairly,
ask another reviewer to take over and say so.

## 5. Handling disagreement

Disagreement is normal and useful; how we resolve it is what matters.

- **Disagree about the code, not the right to hold an opinion.** State your
position, the evidence for it, and the condition under which you would be
persuaded.
- **Prefer the smaller decision.** If two approaches are both correct, prefer the
one that is easier to review and reverse, and note the trade-off.
- **Escalate rather than loop.** If a thread has gone two rounds without
converging, move it to a synchronous call or ask a third maintainer to decide.
Record the outcome on the pull request.
- **A decision is not a defeat.** Once a maintainer resolves an open question,
follow it; if new evidence appears later, reopen it with that evidence.
- **Conduct problems are not code review.** Route harassment or bad-faith
behaviour to [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) and
[`policies/MODERATION.md`](../policies/MODERATION.md), not the comment thread.

## 6. Change log

| Date | Version | Change |
| --- | --- | --- |
| 2026-10-17 | 1.0.0 | Initial release. |
85 changes: 85 additions & 0 deletions Governance/community/SOCIAL_MEDIA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Social Media Policy

| Field | Value |
| --- | --- |
| Document | `Governance/community/SOCIAL_MEDIA.md` |
| Status | Active |
| Version | 1.0.0 |
| Owner | Maintainer Team |
| Last reviewed | 2026-10-17 |
| Review cadence | Every 6 months |
| Applies to | Anyone posting from, or on behalf of, a TeachLink social account |
| Related | [`community/MEDIA_POLICY.md`](MEDIA_POLICY.md) · [`community/REPRESENTATION.md`](REPRESENTATION.md) · [`policies/MODERATION.md`](../policies/MODERATION.md) |

This policy states who may post officially for the project on social media, the
tone and disclosure rules those posts follow, and how a problem with an official
account is escalated. It covers project-operated accounts (for example, the
project's accounts on X, LinkedIn, Mastodon, and the Telegram community), not an
individual's personal account.

## 1. Who may post officially

- **Official accounts are operated by the maintainer team.** Access is granted
per account to named maintainers and, where needed, to a designated community
manager. The current holders are listed in the repository's maintainer records.
- **Only the listed holders may publish** to an official account. Drafting a post
for someone else to publish is fine; publishing from the wrong account is not.
- **Access is least-privilege and reviewed.** Each holder has their own login,
MFA is required, and access is removed when a person leaves the project
([`processes/OFFBOARDING.md`](../processes/OFFBOARDING.md)).
- **Governance and moderation decisions** are announced from the repository (issue
or release notes) first; social posts link to that record rather than being the
only source.

## 2. Tone and disclosure rules

| Do | Avoid |
| --- | --- |
| Match the tone in [`policies/COMMUNICATION_NORMS.md`](../policies/COMMUNICATION_NORMS.md): respectful and factual | Snark, dunking on other projects, or personal attacks |
| Credit contributors and link the relevant PR or issue | Announcing shipped work with no public record |
| Disclose when you are a maintainer speaking in that capacity | Presenting official positions as personal opinion, or vice versa |
| Disclose affiliations and sponsors when they are relevant | Undisclosed promotion of a company you are tied to |
| Correct mistakes openly, with a follow-up post | Quietly deleting a post that made a factual error |

- **No secrets or personal data.** Never post tokens, `.env` values, unpublished
vulnerability details, or user data — the same rule as
[`policies/COMMUNICATION_NORMS.md`](../policies/COMMUNICATION_NORMS.md) §4.4.
- **No unverified claims.** Security, legal, and roadmap claims must be sourced
from a public issue, release note, or advisory. If it is not written down, do
not post it.
- **Personal accounts.** You are free to post as yourself. If you identify as a
maintainer, note that you speak for yourself unless the post is an
announcement; see [`community/REPRESENTATION.md`](REPRESENTATION.md).

## 3. Account security

- MFA and a unique password are mandatory; shared passwords are not permitted.
- Access changes and loss of a device are reported to the maintainer team
immediately so the credential can be rotated. See
[`policies/SECRET_ROTATION.md`](../policies/SECRET_ROTATION.md).
- If an account is compromised, follow
[`processes/ESCALATION_PATH.md`](../processes/ESCALATION_PATH.md): regain
control, then post a short factual notice. Do not argue from the compromised
account.

## 4. Escalation for issues

1. **A problematic post or reply:** report it privately to a maintainer. Do not
start a public argument from an official account.
2. **A conduct or harassment issue:** handle under
[`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md) and
[`policies/MODERATION.md`](../policies/MODERATION.md); the social account is
not the place to resolve it.
3. **A security or privacy concern** raised through social media: move it to the
private channel in [`SECURITY_POLICY.md`](../SECURITY_POLICY.md). Never discuss
an unpatched vulnerability publicly.
4. **A factual error or a legal/compliance concern:** take the post down or
correct it promptly, keep a record of the original, and inform the maintainers.
5. **A missing or departed account holder:** a maintainer with access rotates the
credential and updates the holder list.

## 5. Change log

| Date | Version | Change |
| --- | --- | --- |
| 2026-10-17 | 1.0.0 | Initial release. |
Loading