Skip to content

Commit 32fb9d7

Browse files
jgebaljgebal
authored
Merge pull request #1315 from utPLSQL/feature/configure_duscissions
Implementing github discussions
2 parents d7c0005 + b389671 commit 32fb9d7

File tree

15 files changed

+742
-13
lines changed

15 files changed

+742
-13
lines changed

‎.github/DISCUSSION_TEMPLATE/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# GitHub Discussions — setup guide for utPLSQL/utPLSQL
2+
3+
This folder contains the discussion category form templates that power structured
4+
GitHub Discussions for the utPLSQL project.
5+
6+
---
7+
8+
## File → category mapping
9+
10+
<aside>
11+
The filename slug **must exactly match** the slug GitHub generates for your category name.
12+
GitHub derives the slug by lowercasing the category name and replacing spaces and special
13+
characters with hyphens.
14+
</aside>
15+
16+
| File | Category name to create in GitHub | Format | Who can post |
17+
|------------------------|-----------------------------------|-----------------------|--------------------------------|
18+
| `announcements.yml` | 📢 Announcements | Announcement | Maintainers only |
19+
| `rfcs-design.yml` | 💡 RFCs & Design | Open-ended discussion | Everyone |
20+
| `architecture.yml` | 🏗 Architecture | Open-ended discussion | Everyone |
21+
| `release-planning.yml` | 🗓 Release Planning | Open-ended discussion | Maintainers only (recommended) |
22+
| `q-a.yml` | ❓ Q&A | Question / Answer | Everyone |
23+
| `show-and-tell.yml` | 🔬 Show & Tell | Open-ended discussion | Everyone |
24+
| `contributors.yml` | 🤝 Contributors | Open-ended discussion | Everyone |
25+
| `general.yml` | 💬 General | Open-ended discussion | Everyone |
26+
27+
> **Polls** are a built-in GitHub Discussions type and do not support YAML templates.
28+
> Create a 🗳 Polls category manually (type: Poll) — no template file needed.
29+
30+
---
31+
32+
## Step-by-step setup
33+
34+
### 1. Enable Discussions
35+
Go to **Settings → Features** and check **Discussions**.
36+
37+
### 2. Create the categories
38+
Go to **Discussions → Categories → ✏️ Edit categories** (gear icon).
39+
40+
Create each category listed in the table above.
41+
**Order matters** — drag to set the display order shown below:
42+
43+
1. 📢 Announcements
44+
2. 💡 RFCs & Design
45+
3. 🏗 Architecture
46+
4. 🗓 Release Planning
47+
5. ❓ Q&A
48+
6. 🔬 Show & Tell
49+
7. 🤝 Contributors
50+
8. 🗳 Polls
51+
9. 💬 General
52+
53+
### 3. Commit the templates
54+
Copy all `.yml` files from this folder into `.github/DISCUSSION_TEMPLATE/` in
55+
the **default branch** (usually `develop` for utPLSQL).
56+
57+
```
58+
.github/
59+
└── DISCUSSION_TEMPLATE/
60+
├── announcements.yml
61+
├── rfcs-design.yml
62+
├── architecture.yml
63+
├── release-planning.yml
64+
├── q-a.yml
65+
├── show-and-tell.yml
66+
├── contributors.yml
67+
└── general.yml
68+
```
69+
70+
### 4. Configure category permissions
71+
72+
| Category | Setting |
73+
|------------------|--------------------------------------------------|
74+
| Announcements | Set to **Maintainers only** in category settings |
75+
| Release Planning | Recommended: **Maintainers only** |
76+
| All others | Open to all |
77+
78+
### 5. Create the welcome pinned post
79+
80+
Create a first discussion in **Announcements** titled
81+
**"Welcome to utPLSQL Discussions — how to use this space"**
82+
83+
Suggested body:
84+
85+
```markdown
86+
## Welcome 👋
87+
88+
This is the place for design discussions, feature proposals, and community
89+
conversation around utPLSQL.
90+
91+
### Where to post
92+
93+
| I want to… | Use |
94+
|---|---|
95+
| Propose a new feature or behaviour change | 💡 RFCs & Design |
96+
| Discuss internal architecture | 🏗 Architecture |
97+
| Ask a usage / how-to question | ❓ Q&A |
98+
| Share a CI pipeline, integration, or tip | 🔬 Show & Tell |
99+
| Ask about contributing / development setup | 🤝 Contributors |
100+
| Vote on priorities | 🗳 Polls |
101+
| Anything else | 💬 General |
102+
103+
### Discussions vs Issues
104+
105+
**Discussions** are for ideas that are still open, need input, or require consensus.
106+
**Issues** are for well-scoped work that someone can pick up and implement.
107+
108+
A maintainer will convert a Discussion to an Issue once scope is agreed.
109+
110+
### Real-time chat
111+
112+
For quick questions: [utPLSQL Slack](https://utplsql.slack.com)
113+
For decisions that need a permanent record: post here.
114+
```
115+
116+
Pin this post from the discussion's `…` menu → **Pin discussion**.
117+
118+
### 6. Update the README
119+
120+
Add a Discussions badge to the project README:
121+
122+
```markdown
123+
[![GitHub Discussions](https://img.shields.io/github/discussions/utPLSQL/utPLSQL)](https://github.com/utPLSQL/utPLSQL/discussions)
124+
```
125+
126+
And add a short paragraph in the "Community" or "Contributing" section pointing
127+
to Discussions as the place for design proposals.
128+
129+
---
130+
131+
## Operating guidelines
132+
133+
### Discussion → Issue conversion rule
134+
135+
| Category | Convert when… |
136+
|---------------|----------------------------------------------------------------------|
137+
| RFCs & Design | Consensus reached, scope is defined |
138+
| Architecture | Breaking change formally agreed by maintainers |
139+
| Q&A | A confirmed bug surfaces in the thread |
140+
| Contributors | A gap in docs or tooling is identified that can be filed as an issue |
141+
142+
Use the **"Create issue from discussion"** button (available in the discussion's sidebar).
143+
144+
### Housekeeping
145+
146+
- Lock **Announcements** threads after 30 days.
147+
- Close **Polls** after 14 days; post a summary comment with the result before closing.
148+
- Label cross-references: apply the same labels used on issues
149+
(`enhancement`, `breaking-change`, `coverage`, `oracle-version`, etc.)
150+
to discussions for consistent search.

‎.github/DISCUSSION_TEMPLATE/announcements.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
title: "[Announcement] "
2+
labels: ["announcement"]
3+
body:
4+
- type: markdown
5+
attributes:
6+
value: |
7+
> **Maintainers only.** This category is restricted to project maintainers.
8+
> Announcements are pinned and locked after 30 days.
9+
10+
- type: dropdown
11+
id: announcement_type
12+
attributes:
13+
label: Announcement type
14+
options:
15+
- New release
16+
- Release candidate / pre-release
17+
- Roadmap update
18+
- Deprecation notice
19+
- Security advisory
20+
- Community / governance update
21+
- Other
22+
validations:
23+
required: true
24+
25+
- type: input
26+
id: version
27+
attributes:
28+
label: Version (if applicable)
29+
placeholder: "e.g. 3.2.0"
30+
validations:
31+
required: false
32+
33+
- type: textarea
34+
id: body
35+
attributes:
36+
label: Announcement body
37+
description: |
38+
Write the full announcement here.
39+
For releases, include: highlights, breaking changes, upgrade notes, and a link to the full changelog.
40+
validations:
41+
required: true
42+
43+
- type: textarea
44+
id: links
45+
attributes:
46+
label: Key links
47+
description: Release tag, changelog, migration guide, Docker image, CLI download, etc.
48+
placeholder: |
49+
- Release: https://github.com/utPLSQL/utPLSQL/releases/tag/v…
50+
- Changelog: …
51+
- Docker: …
52+
- CLI: …
53+
validations:
54+
required: false

‎.github/DISCUSSION_TEMPLATE/architecture.yml‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
title: "[Architecture] "
2+
labels: ["architecture", "design"]
3+
body:
4+
- type: markdown
5+
attributes:
6+
value: |
7+
## Architecture discussion
8+
Use this template for internal design decisions: changes to the suite-loading mechanism,
9+
the coverage engine, DDL trigger behaviour, reporter infrastructure, or any
10+
cross-cutting concern that affects the internals of utPLSQL.
11+
12+
This category is primarily for **contributors and maintainers**.
13+
If you want to propose a user-facing feature, use **RFCs & Design** instead.
14+
15+
- type: input
16+
id: title_short
17+
attributes:
18+
label: Component / area
19+
description: Which internal component or subsystem does this discussion concern?
20+
placeholder: "e.g. Suite loader, Coverage engine, Annotation parser, Event system"
21+
validations:
22+
required: true
23+
24+
- type: textarea
25+
id: context
26+
attributes:
27+
label: Context and current design
28+
description: Briefly describe how the relevant part works today.
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: problem
34+
attributes:
35+
label: Problem or design question
36+
description: What specific decision needs to be made, or what limitation needs to be addressed?
37+
validations:
38+
required: true
39+
40+
- type: textarea
41+
id: options
42+
attributes:
43+
label: Options under consideration
44+
description: |
45+
List the design options you are weighing. For each option describe:
46+
- How it works
47+
- Pros
48+
- Cons
49+
- Impact on Oracle compatibility
50+
placeholder: |
51+
**Option A — …**
52+
How: …
53+
Pros: …
54+
Cons: …
55+
56+
**Option B — …**
57+
How: …
58+
Pros: …
59+
Cons: …
60+
validations:
61+
required: true
62+
63+
- type: textarea
64+
id: preferred
65+
attributes:
66+
label: Preferred direction (if any)
67+
description: If you already lean toward one option, say so and why. Leave blank if genuinely open.
68+
validations:
69+
required: false
70+
71+
- type: dropdown
72+
id: breaking
73+
attributes:
74+
label: Does this introduce a breaking change?
75+
options:
76+
- "No"
77+
- "Yes — public API change (ut_runner, ut packages, annotations)"
78+
- "Yes — output/reporter format change"
79+
- "Yes — internal package change (no public API impact)"
80+
- "Unsure"
81+
validations:
82+
required: true
83+
84+
- type: textarea
85+
id: migration
86+
attributes:
87+
label: Migration / compatibility notes
88+
description: If breaking, describe the migration path for users and downstream integrations.
89+
validations:
90+
required: false
91+
92+
- type: checkboxes
93+
id: checklist
94+
attributes:
95+
label: Checklist
96+
options:
97+
- label: I have reviewed the existing architecture docs and source
98+
required: true
99+
- label: Relevant unit / integration tests have been considered
100+
required: false

‎.github/DISCUSSION_TEMPLATE/contributors.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
title: "[Contributors] "
2+
labels: ["contributors"]
3+
body:
4+
- type: markdown
5+
attributes:
6+
value: |
7+
## Contributors
8+
Questions about **contributing to utPLSQL** — development environment setup,
9+
the test suite, pull request process, coding conventions, or anything else
10+
that helps you get your first (or next) contribution merged.
11+
12+
**Useful links before posting:**
13+
- [CONTRIBUTING.md](../../blob/develop/CONTRIBUTING.md)
14+
- [Development environment setup](../../blob/develop/docs/development/developer-guide.md)
15+
- [Open issues labelled `good first issue`](../../issues?q=is%3Aopen+label%3A%22good+first+issue%22)
16+
17+
- type: dropdown
18+
id: topic
19+
attributes:
20+
label: Topic
21+
options:
22+
- Dev environment / Docker setup
23+
- Running the test suite locally
24+
- Understanding the codebase
25+
- PR review process
26+
- Coding conventions / style
27+
- Good first issue — looking for guidance
28+
- Release process
29+
- Documentation contribution
30+
- Other
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: question
36+
attributes:
37+
label: Question or request
38+
description: What do you need help with?
39+
validations:
40+
required: true
41+
42+
- type: textarea
43+
id: context
44+
attributes:
45+
label: What you have tried
46+
description: Steps already taken, error messages, links to relevant code, etc.
47+
validations:
48+
required: false
49+
50+
- type: input
51+
id: os
52+
attributes:
53+
label: Host OS / environment
54+
placeholder: "e.g. macOS 14, Windows 11, Ubuntu 22.04, Docker on Linux"
55+
validations:
56+
required: false

‎.github/DISCUSSION_TEMPLATE/general.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
title: ""
2+
labels: ["general"]
3+
body:
4+
- type: markdown
5+
attributes:
6+
value: |
7+
## General discussion
8+
For open-ended conversations that don't fit another category:
9+
project direction, community topics, suggestions, or anything else.
10+
11+
If your post turns out to be a feature proposal, a maintainer may move it to
12+
**RFCs & Design**. If it is a question about using utPLSQL, consider posting
13+
in **Q&A** instead so a helpful answer can be marked.
14+
15+
- type: textarea
16+
id: body
17+
attributes:
18+
label: What's on your mind?
19+
validations:
20+
required: true
21+
22+
- type: textarea
23+
id: context
24+
attributes:
25+
label: Additional context
26+
description: Background, links, related issues or discussions.
27+
validations:
28+
required: false

0 commit comments

Comments
 (0)