Skip to content

docs: add an org-wide support guide - #52

Merged
uniqueg merged 2 commits into
mainfrom
docs/support
Nov 1, 2026
Merged

uniqueg merged 2 commits into
mainfrom
docs/support

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 1, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds an org-wide SUPPORT.md (default community health file; repositories
don't override it), so GitHub shows support resources when someone opens an
issue:

  • Where to go: Q&A on the discussion board, Slack, the issue forms of the
    affected repository, the security policy for vulnerabilities (never in
    public), email for anything else.
  • Before you ask: read the repository's documentation, search issues and
    discussions.
  • What to include: repository and version, what you tried, logs without
    secrets.
  • What to expect: best-effort community support, no guaranteed response
    times, in English.

The README lists the guide with the other community health files and in its
Contributing section. The channels match the issue chooser's contact links
(#43), which link this guide for email contact.

Closes #44

Light lane

Docs only (one new Markdown file, two README lines), no logic: no reviewer
subagents; I reviewed the diff myself.

How it was verified

  • pre-commit run --all-files (markdownlint, YAML and schema checks,
    gitleaks, shellcheck, actionlint): all passed.
  • CI (Lint, Test, CodeQL, CI passed): passed.
  • pre-commit run --all-files --hook-stage manual gitleaks-all: passed.
  • No links to elixir-cloud-aai.github.io and no deprecated names in the
    changed files.

Declined review findings

  • Sourcery, "private repositories lack default support": same wording as the merged org-wide CONTRIBUTING.md and SECURITY.md; GitHub only requires the .github repository to be public, and repositories do not add their own SUPPORT.md by design.

Fixed: Sourcery, "email questions are discouraged" (f84fd54: email also for questions that can not be asked in public).

Open questions

None.

🤖 Generated with Claude Code

Add SUPPORT.md as a default community health file for every repository:
where to ask (Q&A on the discussion board, Slack, issue forms, the
security policy, email), what to do before asking and what to include,
and what to expect (best-effort community support in English). List it
in the README.

Closes #44

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Reviewer's Guide

Introduces an organization-wide SUPPORT.md with consistent guidance on where and how to request help, then exposes it through the README's community health file list and contribution guidance.

File-Level Changes

Change Details Files
Add an organization-wide support guide covering support channels, request preparation, and community expectations.
  • Direct users to discussions, Slack, repository issue forms, private security reporting, or email based on the request type.
  • Document prerequisites and the repository/version, attempted steps, and sanitized logs to include in support requests.
  • Set best-effort support expectations and English as the support language.
  • Add canonical links for discussions, Q&A, and Slack.
SUPPORT.md
Link the new support guide from the repository README.
  • List the support guide with the other community health files.
  • Reference the guide in the contribution and help guidance.
README.md

Possibly linked issues


Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@uniqueg
uniqueg marked this pull request as ready for review November 1, 2026 03:59

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 2 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="SUPPORT.md" line_range="3-5" />
<code_context>
+# Support
+
+This guide applies to every repository of
+[ELIXIR On-Cloud](https://github.com/elixir-cloud-aai); repositories don't
+have their own `SUPPORT.md`.
+
+## Where to go
</code_context>
<issue_to_address>
**Private repositories lack default support**

When the organization has private repositories, gitHub does not apply organization default community health files to private repositories, so those repositories do not receive this guide unless they add their own support file or link to it.

Scope the claim to public repositories or make the guide available to private repositories through repository-specific support files or another shared mechanism.
</issue_to_address>

### Comment 2
<location path="SUPPORT.md" line_range="9-17" />
<code_context>
+
+## Where to go
+
+- Questions and help with using our projects: the [Q&A][q-a] category of
+  our [discussion board][discussions].
+- Chat with the community: our [Slack][slack].
+- Bugs and feature requests: the issue forms of the affected repository.
+- Vulnerabilities: report them privately, as described in the
+  [security policy](https://github.com/elixir-cloud-aai/.github/blob/main/SECURITY.md),
+  **never** in public issues or discussions.
+- Anything else: email
+  [cloud-service@elixir-europe.org](mailto:cloud-service@elixir-europe.org).
+
+## Before you ask
</code_context>
<issue_to_address>
**Email questions are discouraged**

When someone looking for help reads both organization-wide guides, readers are directed to Q&A or Slack for questions, while email is reserved for “Anything else”; `CONTRIBUTING.md` explicitly lists email as a way to ask questions. This gives users conflicting guidance and discourages an established support channel.

Include email as a question-support channel in `SUPPORT.md`, or update `CONTRIBUTING.md` to make the intended policy consistent.
</issue_to_address>

Linked issues

#44 docs: add an org-wide support guide · 5 of 6 met

# Requirement Status Notes
1 Add an org-wide SUPPORT.md that applies to repositories without their own support guide. ✅ Met SUPPORT.md states that it applies across ELIXIR On-Cloud, and the README identifies it as an organization-wide community health file.
2 Direct users to the requested support channels. ✅ Met The guide covers Q&A, Slack, repository issue forms, private vulnerability reports, and email for anything else.
3 Use the same channels as the issue chooser's contact links (#43). 🟡 Partly met The guide lists the requested channels, but the existing issue chooser still directs questions to the deprecated contact page rather than linking to this guide.
4 Ask users to read the repository documentation and search issues and discussions first. ✅ Met Both steps are in the “Before you ask” section.
5 Ask users to include the repository and version, what they tried, and logs or errors without secrets. ✅ Met The “What to include” list covers these details.
6 Set expectations for best-effort community support, no guaranteed response times, and English. ✅ Met All three expectations appear in the “What to expect” section.

Sourcery assessment

Approval pending. 2 findings to address first.

Blocking findings: SUPPORT.md:5, SUPPORT.md:17


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread SUPPORT.md Resolved
Comment thread SUPPORT.md Resolved
Mention that questions that can't be asked in public go to the email
address, consistent with the contributing guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 35f05b8 into main Nov 1, 2026
6 checks passed
@uniqueg
uniqueg deleted the docs/support branch November 1, 2026 04:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add an org-wide support guide

1 participant