diff --git a/CHANGELOG.md b/CHANGELOG.md index 6677d4c..9ddbeef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,19 @@ All notable changes to QuestionForge are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added + +- **README — a "Development status" section** (the honest maturity framing the sibling suites carry) and a **Support** section. + +### Changed + +- **CONTRIBUTING — sentence-case headings and a standardised licence line.** Corrected + documentation pointers: ADRs live in `docs/decisions/` (not `docs/adr/`), and + significant changes start as an issue or discussion (the repo carries no RFC folder). +- **SECURITY — vulnerability reporting standardised** to GitHub's private vulnerability reporting link, with an aligned supported-versions table and a response-time expectation. + ## [0.1.0] — First public release First public release of QuestionForge: a teacher-led, AI-assisted framework for @@ -23,4 +36,5 @@ exporting them to QTI. - Methodology guides (M1–M5) and a question-format reference. - Getting-started and workflow documentation. +[Unreleased]: https://github.com/tikankika/question-forge/compare/v0.1.0...HEAD [0.1.0]: https://github.com/tikankika/question-forge/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5d576a..bcd57b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,9 +2,27 @@ Thank you for your interest in contributing to QuestionForge! -## How to Contribute +## Critical rules — data protection -### Reporting Bugs +QuestionForge reads real teaching materials (lectures, slides, course documents). +This is a public repository — never let real personal data into the repo, in code, +tests, comments, documentation, examples or commit messages. Git history is permanent. + +- **Never commit real personal data:** names (students, colleagues, teachers), + school or institution names, identifying places, personal-identity numbers, file + paths containing a username (`/Users/...`), secrets (API keys, tokens, `.env`), + and real course materials that identify people or institutions. +- **Use fabricated or anonymised data in every example and test** — for example + `School A`, `Colleague_A`, `/path/to/project`, a fake course code. +- **Watch quasi-identifiers:** a class plus a date plus a subject can identify a + student even with no name attached. +- **Already committed something real?** Deleting the file is not enough — it stays + in the git history forever. Stop, scrub the history, rotate any exposed secret, + and escalate before the next push. + +## How to contribute + +### Reporting bugs 1. Check if the bug is already reported in [Issues](https://github.com/tikankika/question-forge/issues) 2. If not, create a new issue with: @@ -13,15 +31,15 @@ Thank you for your interest in contributing to QuestionForge! - Expected vs actual behaviour - Environment (OS, Python/Node version, Claude Desktop version) -### Suggesting Features +### Suggesting features 1. Open an issue with the `enhancement` label 2. Describe the use case and proposed solution -3. Reference relevant ADRs or RFCs if applicable +3. Reference relevant ADRs (`docs/decisions/`) if applicable -### Code Contributions +### Code contributions -#### Setup Development Environment +#### Setup development environment ```bash # Clone your fork @@ -39,15 +57,15 @@ cd ../qf-scaffolding npm install ``` -#### Development Workflow +#### Development workflow -1. **Check existing ADRs** in `docs/adr/` for architectural context -2. **Create RFC** for significant changes (see `docs/rfcs/` for examples) +1. **Check existing ADRs** in `docs/decisions/` for architectural context +2. **Open an issue or discussion first** for significant changes, so the approach can be agreed before you build 3. **Write tests** for new functionality 4. **Follow code style** (see below) 5. **Update documentation** if needed -#### Code Style +#### Code style **Python (qf-pipeline, qti-core):** - Follow PEP 8 @@ -59,7 +77,7 @@ npm install - Explicit types (avoid `any`) - JSDoc for public functions -#### Commit Messages +#### Commit messages Follow conventional commits: @@ -74,7 +92,7 @@ refactor(step3): simplify fix rule matching Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` -#### Pull Request Process +#### Pull request process 1. Update documentation if needed 2. Add tests for new functionality @@ -82,7 +100,7 @@ Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore` 4. Reference related issues in PR description 5. Request review -### Documentation Contributions +### Documentation contributions Documentation improvements are always welcome: @@ -91,14 +109,13 @@ Documentation improvements are always welcome: - Improve getting started guide - Translate to other languages -## Architecture Overview +## Architecture overview Before contributing code, familiarise yourself with: -- **ADR-001**: Two-MCP architecture (qf-scaffolding + qf-pipeline) -- **ADR-014**: Shared session management -- **docs/rfcs/**: Design proposals and specifications -- **WORKFLOW.md**: Complete workflow documentation +- **README.md**: the two-MCP architecture (qf-scaffolding + qf-pipeline) +- **WORKFLOW.md**: complete workflow documentation +- **docs/decisions/**: architecture decision records (ADRs) ## Communication @@ -106,9 +123,9 @@ Before contributing code, familiarise yourself with: - **Discussions**: Questions and ideas - **Pull Requests**: Code contributions -## License +## Licence -By contributing, you agree that your contributions will be licensed under PolyForm Noncommercial 1.0.0. +By contributing, you agree that your contributions will be licensed under PolyForm Noncommercial 1.0.0 (see [LICENSE](LICENSE)). --- diff --git a/README.md b/README.md index ccb2fbd..50a95f1 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,16 @@ QuestionForge helps educators create pedagogically sound assessment questions th The teacher stays in control at every step — the tools scaffold and document the method; they do not replace the teacher's judgement. +## Development status + +> **This is an active development project, published early.** The end-to-end chain — analyse teaching materials, author questions, validate, and export a QTI package for Inspera — works and is in use. It is shared at this stage deliberately, to invite use and critique. + +**What is solid, and what is still developing:** + +- The **pipeline** (validate question markdown, auto-fix, export to QTI) is the most developed part. +- **M1 (content analysis)** and **M5 (question formatting)** have built scaffolding; **M2–M4** (assessment planning, generation, quality assurance) are methodology-driven through guided dialogue rather than module-specific tools, by design. +- The methodology guides and generated question content are under continual refinement. + ## Part of a teaching-and-assessment ecosystem These tools share one philosophy — *teacher-led: scaffolding, not automation* — and @@ -157,6 +167,11 @@ Instructional materials QuestionForge builds on established research in assessment design — constructive alignment (Biggs & Tang), formative assessment (Black & Wiliam), and Swedish assessment research (Lundahl, Hirsh). +## Support + +- Questions and bugs: [GitHub Issues](https://github.com/tikankika/question-forge/issues) +- Discussion: [GitHub Discussions](https://github.com/tikankika/question-forge/discussions) + --- *QuestionForge — forging quality questions.* diff --git a/SECURITY.md b/SECURITY.md index 4b40be1..e40b732 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,21 +2,16 @@ ## Supported versions -QuestionForge is in early release. Security fixes are provided for the latest -published version only. - | Version | Supported | |---------|-----------| -| 0.1.x | ✅ | -| < 0.1 | ❌ | +| 0.1.x | ✅ | +| < 0.1 | ❌ | ## Reporting a vulnerability Please **do not** open a public issue for security problems. -Report vulnerabilities privately through GitHub's -[private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) -on this repository (the **Security** tab → **Report a vulnerability**). +Report vulnerabilities privately through GitHub's [private vulnerability reporting](https://github.com/tikankika/question-forge/security/advisories/new) (the **Security** tab → **Report a vulnerability**). Please include: @@ -24,9 +19,7 @@ Please include: - steps to reproduce (a minimal example if possible), - any suggested mitigation. -You can expect an acknowledgement within a reasonable time, and we will keep you -informed as the issue is assessed and resolved. Responsible disclosure is -appreciated — please give us time to release a fix before any public disclosure. +You can expect an acknowledgement within a week, and responsible disclosure is appreciated — please allow time for a fix before any public disclosure. ## Scope notes