From 2d949f225618c130d280d28249c4cf27e8a4ce38 Mon Sep 17 00:00:00 2001 From: khaadish Date: Sat, 17 Oct 2026 02:45:15 +0100 Subject: [PATCH] Add community review etiquette, inclusive language, events, and social media policies Closes #1865 Closes #1866 Closes #1867 Closes #1868 --- Governance/community/EVENTS_POLICY.md | 93 ++++++++++++++++++++ Governance/community/INCLUSIVE_LANGUAGE.md | 83 ++++++++++++++++++ Governance/community/REVIEW_ETIQUETTE.md | 99 ++++++++++++++++++++++ Governance/community/SOCIAL_MEDIA.md | 85 +++++++++++++++++++ 4 files changed, 360 insertions(+) create mode 100644 Governance/community/EVENTS_POLICY.md create mode 100644 Governance/community/INCLUSIVE_LANGUAGE.md create mode 100644 Governance/community/REVIEW_ETIQUETTE.md create mode 100644 Governance/community/SOCIAL_MEDIA.md diff --git a/Governance/community/EVENTS_POLICY.md b/Governance/community/EVENTS_POLICY.md new file mode 100644 index 00000000..779400f8 --- /dev/null +++ b/Governance/community/EVENTS_POLICY.md @@ -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. | diff --git a/Governance/community/INCLUSIVE_LANGUAGE.md b/Governance/community/INCLUSIVE_LANGUAGE.md new file mode 100644 index 00000000..4c0ff44d --- /dev/null +++ b/Governance/community/INCLUSIVE_LANGUAGE.md @@ -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. | diff --git a/Governance/community/REVIEW_ETIQUETTE.md b/Governance/community/REVIEW_ETIQUETTE.md new file mode 100644 index 00000000..9fe04a3a --- /dev/null +++ b/Governance/community/REVIEW_ETIQUETTE.md @@ -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. | diff --git a/Governance/community/SOCIAL_MEDIA.md b/Governance/community/SOCIAL_MEDIA.md new file mode 100644 index 00000000..88e7b357 --- /dev/null +++ b/Governance/community/SOCIAL_MEDIA.md @@ -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. |