Skip to content

Commit b077f3f

Browse files
lex57ukrlex57ukr
authored
Add lightweight GitHub Issue templates for tasks and bugs (#19)
* Add issue templates for bug reports and tasks * Enhance pull request template with guidance on special labels * Add contributing guidelines to CONTRIBUTING.md * Add directory for issue templates in .github * Clarify branch naming convention in workflow documentation
1 parent 258cf0a commit b077f3f

7 files changed

Lines changed: 183 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: Bug report
3+
about: Something is not working as expected
4+
labels: bug
5+
---
6+
7+
## What happened
8+
9+
<!--
10+
Describe the observed behavior.
11+
-->
12+
13+
## What was expected
14+
15+
<!--
16+
Describe what you expected to happen.
17+
-->
18+
19+
## Steps to reproduce
20+
21+
<!--
22+
Minimal steps, if known.
23+
-->
24+
25+
## Environment
26+
27+
<!--
28+
OS, version, CLI version, or other relevant context.
29+
-->
30+
31+
## Notes
32+
33+
<!--
34+
Optional additional context.
35+
-->

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
blank_issues_enabled: true

‎.github/ISSUE_TEMPLATE/task.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
name: Task / Enhancement
3+
about: Planned work, improvements, or operational tasks
4+
labels: enhancement
5+
---
6+
7+
## Goal
8+
9+
<!--
10+
What outcome are we trying to achieve?
11+
Focus on intent, not implementation.
12+
-->
13+
14+
## Scope
15+
16+
<!--
17+
High-level bullets describing what is included.
18+
Avoid premature technical detail.
19+
-->
20+
21+
-
22+
-
23+
-
24+
25+
## Outcome
26+
27+
<!--
28+
What will be clearer, safer, faster, or more reliable once this is done?
29+
-->
30+
31+
## Notes
32+
33+
<!--
34+
Optional context, constraints, or links.
35+
-->

‎.github/pull_request_template.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
PR workflow reminder:
33
- Use a clear, outcome-focused title (this becomes a release note entry)
44
- Apply appropriate labels (e.g. enhancement, documentation, bug)
5+
- Use special labels (`breaking-change`, `security`, `dependencies`) intentionally — they affect release notes
56
- Reference related issues using `Refs #NN` or `Fixes #NN`
67
- Squash merge is preferred unless stated otherwise
78
-->

‎CLAUDE.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,14 @@ keystone-cli/
3333
│ │ └── how-to-workflow.md # Development workflow guide
3434
│ └── man/ # Manual pages in mdoc format
3535
├── .github/
36+
│ ├── ISSUE_TEMPLATE/ # Issue templates
3637
│ ├── workflows/ # GitHub Actions
3738
│ │ ├── ci.yml # CI pipeline (tests on PR/push)
3839
│ │ ├── release.yml # Release build and publish
3940
│ │ └── tag-release.yml # Manual tag creation workflow
4041
│ ├── pull_request_template.md # PR template
4142
│ └── release.yml # Release notes configuration
43+
├── CONTRIBUTING.md # Contribution guidelines
4244
├── scripts/ # Build and utility scripts
4345
│ └── package-release.sh # Tarball packaging script
4446
├── artifacts/ # Build outputs

‎CONTRIBUTING.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Contributing to Keystone CLI
2+
3+
Thank you for your interest in contributing to Keystone CLI. This document provides guidelines
4+
and pointers to help you get started.
5+
6+
## Getting Started
7+
8+
1. Fork the repository
9+
2. Clone your fork locally
10+
3. Review the [README](README.md) for project overview and installation instructions
11+
4. Review [CLAUDE.md](CLAUDE.md) for development commands and architecture details
12+
13+
## Development Setup
14+
15+
The project uses .NET 10.0 and follows clean architecture principles.
16+
17+
```bash
18+
# Build the project
19+
dotnet build
20+
21+
# Run tests
22+
dotnet test
23+
24+
# Run the CLI
25+
dotnet run --project src/Keystone.Cli
26+
```
27+
28+
For complete build commands, testing options, and architecture details, see [CLAUDE.md](CLAUDE.md).
29+
30+
## Reporting Issues
31+
32+
Before opening an issue, search existing issues to avoid duplicates.
33+
34+
### Bug Reports
35+
36+
Use the [bug report template](.github/ISSUE_TEMPLATE/bug.md) for issues where something is not
37+
working as expected. Include:
38+
39+
- What happened vs. what was expected
40+
- Steps to reproduce
41+
- Environment details (OS, CLI version)
42+
43+
### Feature Requests and Tasks
44+
45+
Use the [task template](.github/ISSUE_TEMPLATE/task.md) for enhancements, improvements, or
46+
planned work. Focus on outcomes rather than implementation details.
47+
48+
## Submitting Changes
49+
50+
This project follows a structured workflow documented in
51+
[docs/how-to/how-to-workflow.md](docs/how-to/how-to-workflow.md).
52+
53+
### Quick Reference
54+
55+
1. Create a branch for your work
56+
2. Make your changes with clear, focused commits
57+
3. Ensure tests pass: `dotnet test`
58+
4. Open a pull request using the [PR template](.github/pull_request_template.md)
59+
5. Use an outcome-focused PR title (it becomes a release note entry)
60+
6. Reference related issues with `Fixes #N` or `Refs #N`
61+
7. Apply appropriate labels (`bug`, `enhancement`, `documentation`)
62+
63+
### Code Quality
64+
65+
- The project uses `TreatWarningsAsErrors` — all warnings must be resolved
66+
- Follow existing code patterns and architecture
67+
- Include unit tests for new functionality
68+
- Run `dotnet test` before submitting
69+
70+
## Labels
71+
72+
Apply labels to issues and PRs. Labels determine how changes are grouped in auto-generated
73+
release notes. See [.github/release.yml](.github/release.yml) for the full categorization
74+
configuration.
75+
76+
| Label | Use For |
77+
|--------------------|---------------------------------------------|
78+
| `breaking-change` | Incompatible API or behavior change |
79+
| `security` | Security fixes or improvements |
80+
| `enhancement` | New feature or improvement |
81+
| `bug` | Something is broken |
82+
| `documentation` | Documentation changes |
83+
| `dependencies` | Dependency updates |
84+
| `question` | Clarification or discussion |
85+
| `good-first-issue` | Good for newcomers |
86+
| `help-wanted` | Extra attention needed |
87+
| `duplicate` | Duplicate issue (excluded from notes) |
88+
| `invalid` | Not valid (excluded from notes) |
89+
| `wont-fix` | Will not be addressed (excluded from notes) |
90+
91+
## Release Process
92+
93+
Releases are tag-driven and automated. For maintainers, the complete release process is
94+
documented in [docs/how-to/how-to-release.md](docs/how-to/how-to-release.md).
95+
96+
## Additional Resources
97+
98+
- [Development workflow](docs/how-to/how-to-workflow.md) — issue tracking, PRs, and merging
99+
- [Release process](docs/how-to/how-to-release.md) — version management and publishing
100+
- [Testing man pages](docs/how-to/how-to-test-man-page.md) — local man page validation
101+
- [Architecture and commands](CLAUDE.md) — project structure and development reference
102+
103+
## Questions
104+
105+
For questions or discussion, open an issue with the `question` label or start a
106+
[GitHub Discussion](https://github.com/knight-owl-dev/keystone-cli/discussions) if enabled.

‎docs/how-to/how-to-workflow.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,12 @@ Issues act as lightweight tickets and historical context.
2424

2525
### 2. Working on an Issue
2626

27-
- Create a branch for the work (naming is flexible but should be descriptive)
27+
- Create a branch for the work
2828
- Implement the change
2929
- Commit freely during development
3030

31-
Branch naming is optional and does not affect automation.
31+
Prefer the `issue-NN-short-description` naming convention (e.g., `issue-42-fix-login-bug`).
32+
This is not enforced but aids traceability.
3233

3334
### 3. Opening a Pull Request
3435

0 commit comments

Comments
 (0)