From e81f03486d8a589e0730bb502296fb3156a59190 Mon Sep 17 00:00:00 2001 From: DongHun Date: Thu, 19 Nov 2026 14:18:41 +0900 Subject: [PATCH] Improve the first contribution experience --- .github/ISSUE_TEMPLATE/bug_report.md | 18 ++++++++----- .github/ISSUE_TEMPLATE/feature_request.md | 14 ++++++---- .github/PULL_REQUEST_TEMPLATE.md | 6 ++--- CONTRIBUTING.md | 31 +++++++++++++++-------- README.md | 4 +-- 5 files changed, 46 insertions(+), 27 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 134423f..955b5ed 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,18 +1,22 @@ --- name: Bug report -about: Report a bug that can be reproduced with synthetic data +about: Report an error or unexpected behavior in Danseo title: "" --- - + -## Problem and expected behavior +## What happened? + +What did you expect, and what did you see instead? ## Environment -- Version or commit: -- OS, Node.js, and npm versions: +- OS and shell: +- Danseo version or source commit (or ZIP branch and download date, if known): +- Agent and skill installation method, if applicable: +- Node.js version (and npm version if used): -## Steps to reproduce and actual behavior +## Steps to reproduce -Include the commands you ran and a minimal synthetic example. Keep personal paths, research materials, tokens, and exported evidence bundles private. Follow the [security policy](https://github.com/OstenHun/danseo/blob/main/SECURITY.md) to report vulnerabilities privately. +List the steps or commands and include a small synthetic example if you can. If the bug only happens with private files, share the steps and a redacted error message. Keep personal paths, research files, tokens, and exported evidence bundles private. Follow the [security policy](https://github.com/OstenHun/danseo/blob/main/SECURITY.md) to report vulnerabilities privately. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 14a78d5..248f785 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -4,12 +4,16 @@ about: Describe a problem and the behavior that would solve it title: "" --- - + -## Problem to solve +## What are you trying to do? -## Current approach and limitations +Describe the task and where you get stuck. -## Desired behavior and how to verify it +## What have you tried? -Use an example you can share publicly. +If you have a workaround, explain what it does and where it falls short. + +## What would help? + +Describe the behavior you want and how you would tell it works. Use an example you can share publicly. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ff97211..7878ee3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,12 +1,12 @@ - + ## What changed and why ## Verification -List the commands you ran, their results, and any checks still pending. +List the checks you ran and their results. Mention any checks you skipped. For documentation-only changes, include the result of `npm run check:docs`. -## Remaining checks +## Checklist - [ ] I kept private materials, local paths, and secrets out of this pull request. - [ ] I checked the attribution and licenses of any third-party code or materials included here. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6777e74..3df2dda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,29 @@ # Contributing to Danseo -Summary: Propose focused changes with synthetic reproductions. Use Node 24 for development, check Node 22/24 compatibility, and keep research evidence, private material, and product behavior distinct. +Summary: Report a bug, propose an improvement, or make your first pull request. Use public or synthetic examples, keep changes focused, and share the checks you ran. + +## Report a bug or suggest a feature + +Search [existing issues](https://github.com/OstenHun/danseo/issues) for the same problem. If you find one, add any new steps or environment details there. Otherwise, [open an issue](https://github.com/OstenHun/danseo/issues/new/choose) and choose a template. Please open one issue per bug or feature request. Write the title and body in English. + +- **Bug report:** Name the workflow and what failed. An example title is `Standalone skill: no HTML file after generating a graph`. Include your environment, the steps or command, and what you expected and observed. +- **Feature request:** Describe what you were trying to do, where the current workflow gets in the way, and what result would help. Discuss the scope in an issue before adding a dependency, file format, or external service. + +To identify the source version, run `git rev-parse --short HEAD` in the Danseo checkout, or give the branch and download date of your source ZIP if known. For a standalone skill bug, include your agent and how you installed the skill. + +Use a small synthetic example when possible. If the bug only happens with private material, share the steps and a redacted error message instead. Use the [security policy](SECURITY.md) for private vulnerability reporting. + +## Make your first contribution + +Browse the open [good first issues](https://github.com/OstenHun/danseo/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22). If the list is empty, a small documentation fix, a synthetic example, or a report from another environment is welcome. + +1. Fork Danseo, clone your fork, and create a branch for one change. +2. Make the change and run the relevant checks. For a documentation-only change, start with `npm ci` and `npm run check:docs`. For a behavior change, run the relevant tests and add a regression check where appropriate. +3. Push the branch to your fork and open a pull request against `OstenHun/danseo:main`. Link the related issue if there is one. Explain why the change helps, which checks you ran, and which checks remain. ## Development setup -The development default is Node 24, as specified in `.node-version`. Check runtime API changes on supported Node 22 and 24 versions. Node 26 checks provide an early compatibility signal. The [runtime policy](docs/RUNTIME_SUPPORT.md) (Korean) owns support changes and patch updates. +The development default is Node 24, as specified in `.node-version`. Check runtime API changes on supported Node 22 and 24 versions. Node 26 checks provide an early compatibility signal. See the [runtime policy](docs/RUNTIME_SUPPORT.md) for supported versions and patch updates, and the [roadmap](TASKS.md) for project scope. ```sh npm ci @@ -45,14 +64,6 @@ npm run check:docs `ok()` checks CLI success before returning a command-specific response type. The explicit type boundary in `parseJson()` does not replace runtime JSON validation. Use `json()` and `run()` for intentionally damaged inputs and invalid requests. `required()` also checks fixture-item presence at runtime. Product card, claim, and review types come from `dist/` declarations; test-only contracts belong in `fixture-types.ts`. -## Proposing changes - -For bugs, include your environment, command, expected and actual results, and a minimal synthetic reproduction. For features, describe the problem and the limits of the current approach. Discuss scope before introducing a dependency, file format, or external service. - -Keep each PR focused on one problem. Describe the change, checks actually run, their results, and remaining limits. Add a regression check for behavior changes where appropriate. Documentation-only edits do not need tests that merely repeat the wording. - -Use [Issues](https://github.com/OstenHun/danseo/issues) for proposals and bugs, and [Pull requests](https://github.com/OstenHun/danseo/pulls) for change review. The [task list](TASKS.md) (Korean) remains the canonical development tracker; do not manually duplicate the same status across trackers. - ## Evidence and private material - Use synthetic examples or material whose publication and redistribution rights have been checked. diff --git a/README.md b/README.md index c809ef8..6a11f16 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ This preview connects [*Attention Is All You Need*](https://arxiv.org/abs/1706.0 ![Node.js 22 or 24 LTS](https://img.shields.io/badge/node-22%20%7C%2024%20LTS-43853d.svg) ![Development preview](https://img.shields.io/badge/status-development_preview-orange.svg) -[Korean README](README.ko.md) · [Documentation](docs/README.md) +[Korean README](README.ko.md) · [Documentation](docs/README.md) · [Contribute](CONTRIBUTING.md) · [Open an issue](https://github.com/OstenHun/danseo/issues/new/choose) @@ -197,6 +197,6 @@ Source checks cover the displayed evidence. Results depend on which sources the ## Contributing and license -Bug reproductions, clearer documentation, synthetic examples, and reports from other environments are welcome. See [contributing](CONTRIBUTING.md) and [security](SECURITY.md). Keep private papers, research notes, and model logs out of public reports. +Bug reproductions, clearer documentation, synthetic examples, and reports from other environments are welcome. Read the [first contribution guide](CONTRIBUTING.md#make-your-first-contribution) or browse [good first issues](https://github.com/OstenHun/danseo/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22). Use the [security policy](SECURITY.md) to report vulnerabilities privately. Code, documentation, skills, and synthetic examples use the [MIT License](LICENSE). Papers, datasets, and user-supplied material retain their own terms. See [third-party notices](THIRD_PARTY_NOTICES.md).