Skip to content

Implementing github discussions #1315

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
jgebal merged 1 commit into from
Mar 16, 2026
Merged

Implementing github discussions #1315

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
150 changes: 150 additions & 0 deletions .github/DISCUSSION_TEMPLATE/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
# GitHub Discussions — setup guide for utPLSQL/utPLSQL

This folder contains the discussion category form templates that power structured
GitHub Discussions for the utPLSQL project.

---

## File → category mapping

<aside>
The filename slug **must exactly match** the slug GitHub generates for your category name.
GitHub derives the slug by lowercasing the category name and replacing spaces and special
characters with hyphens.
</aside>

| File | Category name to create in GitHub | Format | Who can post |
|------------------------|-----------------------------------|-----------------------|--------------------------------|
| `announcements.yml` | 📢 Announcements | Announcement | Maintainers only |
| `rfcs-design.yml` | 💡 RFCs & Design | Open-ended discussion | Everyone |
| `architecture.yml` | 🏗 Architecture | Open-ended discussion | Everyone |
| `release-planning.yml` | 🗓 Release Planning | Open-ended discussion | Maintainers only (recommended) |
| `q-a.yml` | ❓ Q&A | Question / Answer | Everyone |
| `show-and-tell.yml` | 🔬 Show & Tell | Open-ended discussion | Everyone |
| `contributors.yml` | 🤝 Contributors | Open-ended discussion | Everyone |
| `general.yml` | 💬 General | Open-ended discussion | Everyone |

> **Polls** are a built-in GitHub Discussions type and do not support YAML templates.
> Create a 🗳 Polls category manually (type: Poll) — no template file needed.

---

## Step-by-step setup

### 1. Enable Discussions
Go to **Settings → Features** and check **Discussions**.

### 2. Create the categories
Go to **Discussions → Categories → ✏️ Edit categories** (gear icon).

Create each category listed in the table above.
**Order matters** — drag to set the display order shown below:

1. 📢 Announcements
2. 💡 RFCs & Design
3. 🏗 Architecture
4. 🗓 Release Planning
5. ❓ Q&A
6. 🔬 Show & Tell
7. 🤝 Contributors
8. 🗳 Polls
9. 💬 General

### 3. Commit the templates
Copy all `.yml` files from this folder into `.github/DISCUSSION_TEMPLATE/` in
the **default branch** (usually `develop` for utPLSQL).

```
.github/
└── DISCUSSION_TEMPLATE/
├── announcements.yml
├── rfcs-design.yml
├── architecture.yml
├── release-planning.yml
├── q-a.yml
├── show-and-tell.yml
├── contributors.yml
└── general.yml
```

### 4. Configure category permissions

| Category | Setting |
|------------------|--------------------------------------------------|
| Announcements | Set to **Maintainers only** in category settings |
| Release Planning | Recommended: **Maintainers only** |
| All others | Open to all |

### 5. Create the welcome pinned post

Create a first discussion in **Announcements** titled
**"Welcome to utPLSQL Discussions — how to use this space"**

Suggested body:

```markdown
## Welcome 👋

This is the place for design discussions, feature proposals, and community
conversation around utPLSQL.

### Where to post

| I want to… | Use |
|---|---|
| Propose a new feature or behaviour change | 💡 RFCs & Design |
| Discuss internal architecture | 🏗 Architecture |
| Ask a usage / how-to question | ❓ Q&A |
| Share a CI pipeline, integration, or tip | 🔬 Show & Tell |
| Ask about contributing / development setup | 🤝 Contributors |
| Vote on priorities | 🗳 Polls |
| Anything else | 💬 General |

### Discussions vs Issues

**Discussions** are for ideas that are still open, need input, or require consensus.
**Issues** are for well-scoped work that someone can pick up and implement.

A maintainer will convert a Discussion to an Issue once scope is agreed.

### Real-time chat

For quick questions: [utPLSQL Slack](https://utplsql.slack.com)
For decisions that need a permanent record: post here.
```

Pin this post from the discussion's `…` menu → **Pin discussion**.

### 6. Update the README

Add a Discussions badge to the project README:

```markdown
[![GitHub Discussions](https://img.shields.io/github/discussions/utPLSQL/utPLSQL)](https://github.com/utPLSQL/utPLSQL/discussions)
```

And add a short paragraph in the "Community" or "Contributing" section pointing
to Discussions as the place for design proposals.

---

## Operating guidelines

### Discussion → Issue conversion rule

| Category | Convert when… |
|---------------|----------------------------------------------------------------------|
| RFCs & Design | Consensus reached, scope is defined |
| Architecture | Breaking change formally agreed by maintainers |
| Q&A | A confirmed bug surfaces in the thread |
| Contributors | A gap in docs or tooling is identified that can be filed as an issue |

Use the **"Create issue from discussion"** button (available in the discussion's sidebar).

### Housekeeping

- Lock **Announcements** threads after 30 days.
- Close **Polls** after 14 days; post a summary comment with the result before closing.
- Label cross-references: apply the same labels used on issues
(`enhancement`, `breaking-change`, `coverage`, `oracle-version`, etc.)
to discussions for consistent search.
54 changes: 54 additions & 0 deletions .github/DISCUSSION_TEMPLATE/announcements.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
title: "[Announcement] "
labels: ["announcement"]
body:
- type: markdown
attributes:
value: |
> **Maintainers only.** This category is restricted to project maintainers.
> Announcements are pinned and locked after 30 days.

- type: dropdown
id: announcement_type
attributes:
label: Announcement type
options:
- New release
- Release candidate / pre-release
- Roadmap update
- Deprecation notice
- Security advisory
- Community / governance update
- Other
validations:
required: true

- type: input
id: version
attributes:
label: Version (if applicable)
placeholder: "e.g. 3.2.0"
validations:
required: false

- type: textarea
id: body
attributes:
label: Announcement body
description: |
Write the full announcement here.
For releases, include: highlights, breaking changes, upgrade notes, and a link to the full changelog.
validations:
required: true

- type: textarea
id: links
attributes:
label: Key links
description: Release tag, changelog, migration guide, Docker image, CLI download, etc.
placeholder: |
- Release: https://github.com/utPLSQL/utPLSQL/releases/tag/v…
- Changelog: …
- Docker: …
- CLI: …
validations:
required: false
100 changes: 100 additions & 0 deletions .github/DISCUSSION_TEMPLATE/architecture.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
title: "[Architecture] "
labels: ["architecture", "design"]
body:
- type: markdown
attributes:
value: |
## Architecture discussion
Use this template for internal design decisions: changes to the suite-loading mechanism,
the coverage engine, DDL trigger behaviour, reporter infrastructure, or any
cross-cutting concern that affects the internals of utPLSQL.

This category is primarily for **contributors and maintainers**.
If you want to propose a user-facing feature, use **RFCs & Design** instead.

- type: input
id: title_short
attributes:
label: Component / area
description: Which internal component or subsystem does this discussion concern?
placeholder: "e.g. Suite loader, Coverage engine, Annotation parser, Event system"
validations:
required: true

- type: textarea
id: context
attributes:
label: Context and current design
description: Briefly describe how the relevant part works today.
validations:
required: true

- type: textarea
id: problem
attributes:
label: Problem or design question
description: What specific decision needs to be made, or what limitation needs to be addressed?
validations:
required: true

- type: textarea
id: options
attributes:
label: Options under consideration
description: |
List the design options you are weighing. For each option describe:
- How it works
- Pros
- Cons
- Impact on Oracle compatibility
placeholder: |
**Option A — …**
How: …
Pros: …
Cons: …

**Option B — …**
How: …
Pros: …
Cons: …
validations:
required: true

- type: textarea
id: preferred
attributes:
label: Preferred direction (if any)
description: If you already lean toward one option, say so and why. Leave blank if genuinely open.
validations:
required: false

- type: dropdown
id: breaking
attributes:
label: Does this introduce a breaking change?
options:
- "No"
- "Yes — public API change (ut_runner, ut packages, annotations)"
- "Yes — output/reporter format change"
- "Yes — internal package change (no public API impact)"
- "Unsure"
validations:
required: true

- type: textarea
id: migration
attributes:
label: Migration / compatibility notes
description: If breaking, describe the migration path for users and downstream integrations.
validations:
required: false

- type: checkboxes
id: checklist
attributes:
label: Checklist
options:
- label: I have reviewed the existing architecture docs and source
required: true
- label: Relevant unit / integration tests have been considered
required: false
56 changes: 56 additions & 0 deletions .github/DISCUSSION_TEMPLATE/contributors.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
title: "[Contributors] "
labels: ["contributors"]
body:
- type: markdown
attributes:
value: |
## Contributors
Questions about **contributing to utPLSQL** — development environment setup,
the test suite, pull request process, coding conventions, or anything else
that helps you get your first (or next) contribution merged.

**Useful links before posting:**
- [CONTRIBUTING.md](../../blob/develop/CONTRIBUTING.md)
- [Development environment setup](../../blob/develop/docs/development/developer-guide.md)
- [Open issues labelled `good first issue`](../../issues?q=is%3Aopen+label%3A%22good+first+issue%22)

- type: dropdown
id: topic
attributes:
label: Topic
options:
- Dev environment / Docker setup
- Running the test suite locally
- Understanding the codebase
- PR review process
- Coding conventions / style
- Good first issue — looking for guidance
- Release process
- Documentation contribution
- Other
validations:
required: true

- type: textarea
id: question
attributes:
label: Question or request
description: What do you need help with?
validations:
required: true

- type: textarea
id: context
attributes:
label: What you have tried
description: Steps already taken, error messages, links to relevant code, etc.
validations:
required: false

- type: input
id: os
attributes:
label: Host OS / environment
placeholder: "e.g. macOS 14, Windows 11, Ubuntu 22.04, Docker on Linux"
validations:
required: false
28 changes: 28 additions & 0 deletions .github/DISCUSSION_TEMPLATE/general.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
title: ""
labels: ["general"]
body:
- type: markdown
attributes:
value: |
## General discussion
For open-ended conversations that don't fit another category:
project direction, community topics, suggestions, or anything else.

If your post turns out to be a feature proposal, a maintainer may move it to
**RFCs & Design**. If it is a question about using utPLSQL, consider posting
in **Q&A** instead so a helpful answer can be marked.

- type: textarea
id: body
attributes:
label: What's on your mind?
validations:
required: true

- type: textarea
id: context
attributes:
label: Additional context
description: Background, links, related issues or discussions.
validations:
required: false
Loading
Loading