From 170e9dbea87afb0ba47b5cc6ea2dec4c3f5f513c Mon Sep 17 00:00:00 2001 From: tikankika Date: Mon, 6 Jul 2026 19:01:18 +0200 Subject: [PATCH 1/2] docs: polish community files for public readers - README: add a development-status section (honest maturity framing) and a support section - CHANGELOG: add an unreleased section covering this batch - CONTRIBUTING: add critical data-protection rules, sentence-case headings, standardised licence line - SECURITY: direct private-vulnerability-reporting link, aligned supported-versions table, concrete response-time expectation Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 12 ++++++++++++ CONTRIBUTING.md | 44 +++++++++++++++++++++++++++++++------------- README.md | 15 +++++++++++++++ SECURITY.md | 15 ++++----------- 4 files changed, 62 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6677d4c..3ea0e29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ 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.** +- **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 +34,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..460d275 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 -### Code Contributions +### Code contributions -#### Setup Development Environment +#### Setup development environment ```bash # Clone your fork @@ -39,7 +57,7 @@ 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) @@ -47,7 +65,7 @@ npm install 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,7 +109,7 @@ Documentation improvements are always welcome: - Improve getting started guide - Translate to other languages -## Architecture Overview +## Architecture overview Before contributing code, familiarise yourself with: @@ -106,9 +124,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 85232c0..665df1a 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 From ed78ac1cd8a6a444db1699f4941f4cbcb1642ac7 Mon Sep 17 00:00:00 2001 From: tikankika Date: Tue, 7 Jul 2026 08:41:42 +0200 Subject: [PATCH 2/2] docs(contributing): point at documentation that exists in the repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ADRs live in docs/decisions/, not docs/adr/ - RFCs are internal and the repo has no docs/rfcs/ — significant changes start as an issue or discussion instead - Architecture overview now lists README, WORKFLOW and docs/decisions/ rather than internal-only ADR numbers - CHANGELOG unreleased entry updated to cover the corrections Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 4 +++- CONTRIBUTING.md | 13 ++++++------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ea0e29..9ddbeef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- **CONTRIBUTING — sentence-case headings and a standardised licence line.** +- **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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 460d275..bcd57b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ tests, comments, documentation, examples or commit messages. Git history is perm 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 @@ -59,8 +59,8 @@ npm install #### 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 @@ -113,10 +113,9 @@ Documentation improvements are always welcome: 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