diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..905cd88 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,92 @@ +name: Bug report +description: Report a reproducible problem with HeimForge +title: "fix: " +body: + - type: markdown + attributes: + value: | + Thanks for reporting a HeimForge problem. + + Do not include credentials, private keys, access tokens, private server + configuration, or other secrets. Security vulnerabilities should follow + SECURITY.md instead of being reported here. + + - type: dropdown + id: area + attributes: + label: Affected area + options: + - Generator / bootstrap + - Generated template + - Metadata / validation + - Build / test tooling + - Packaging + - Deployment + - Documentation + - Release automation + - Other + validations: + required: true + + - type: input + id: version + attributes: + label: HeimForge version or commit + description: Release tag or commit SHA where the problem occurs. + placeholder: "v0.7.1 or abc1234" + validations: + required: true + + - type: input + id: environment + attributes: + label: Environment + description: Include OS/WSL distribution and relevant Python/.NET versions. + placeholder: "WSL2 Ubuntu 24.04, Python 3.12, .NET 8" + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction steps + description: Provide the smallest sequence that reliably reproduces the problem. + placeholder: | + 1. Run ... + 2. Generate ... + 3. Observe ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Relevant output + description: Paste relevant logs or error output after removing secrets and private data. + render: shell + + - type: checkboxes + id: checks + attributes: + label: Checklist + options: + - label: I searched existing issues for the same problem. + required: true + - label: I removed credentials, private configuration, and other secrets from the report. + required: true + - label: This concerns HeimForge or generated HeimForge infrastructure, not Vibeheim-specific gameplay. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..ece0721 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/heimforge-dev/heimforge/security/policy + about: Report security issues privately using the instructions in SECURITY.md. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..1fc1af1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,65 @@ +name: Feature request +description: Propose an improvement to HeimForge or its generated scaffold +title: "feat: " +body: + - type: markdown + attributes: + value: | + HeimForge's template is intentionally generic. Vibeheim-specific or other + project-specific gameplay features belong in those projects rather than + in HeimForge. + + - type: dropdown + id: area + attributes: + label: Area + options: + - Generator / bootstrap + - Generated template + - Metadata / validation + - Build / test tooling + - Packaging + - Deployment + - Documentation + - Release automation + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem + description: What problem or limitation would this change address? + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed change + description: Describe the behavior or interface you would like. + validations: + required: true + + - type: textarea + id: generated + attributes: + label: Effect on generated repositories + description: Describe whether this changes generated output, compatibility, or maintenance requirements. + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Optional approaches or workarounds you considered. + + - type: checkboxes + id: checks + attributes: + label: Checklist + options: + - label: I searched existing issues for a similar request. + required: true + - label: This is generic HeimForge infrastructure rather than project-specific gameplay. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8f3a359 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## Summary + + + +## Validation + + + +- [ ] `git diff --check` +- [ ] Relevant targeted tests +- [ ] `./scripts/validate-template.sh` if `template/` changed +- [ ] `./scripts/test.sh` for broad or cross-cutting changes, when warranted + +## Checklist + +- [ ] The change is focused and scoped to HeimForge. +- [ ] Generated repositories remain standalone and do not depend on HeimForge. +- [ ] Generic template code contains no project-specific gameplay. +- [ ] No credentials, machine-local configuration, game assemblies, or world data are included. +- [ ] The Apache-2.0 / MIT-0 licensing boundary is preserved. +- [ ] Documentation was updated where behavior or maintenance procedures changed. +- [ ] Generated output and tests were updated together when applicable. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5b075fb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,112 @@ +# Contributing to HeimForge + +HeimForge is a generator for standalone Valheim mod-suite repositories. Changes +to HeimForge should preserve the boundary between the generator itself and the +independent repositories produced from `template/`. + +## Development environment + +HeimForge is developed and tested primarily under WSL2/Linux. + +Requirements: + +- Git with submodule support +- Python 3.10 or newer +- .NET 8 SDK for the full generated-project test suite + +Clone with submodules: + +```bash +git clone --recurse-submodules https://github.com/heimforge-dev/heimforge.git +cd heimforge +``` + +If the repository was cloned without submodules: + +```bash +git submodule update --init --recursive +``` + +## Repository structure + +- `bootstrap/` contains the Python generator. +- `template/` is the complete standalone project scaffold copied into generated repositories. +- `tests/bootstrap/` contains generator tests. +- `tests/template/` contains template and generated-project tests. +- `docs/` contains HeimForge architecture and maintenance documentation. + +For detailed repository constraints, also read `AGENTS.md` and +`docs/TEMPLATE_MAINTENANCE.md`. + +## Making changes + +Keep changes focused and preserve these boundaries: + +- Generated repositories must remain standalone and must not depend on a + HeimForge checkout. +- `template/` must remain generic. Project-specific gameplay such as Vibeheim + features does not belong in HeimForge. +- Do not perform repository-wide identity replacement. Generator identity + substitution is controlled by the documented template token system. +- Do not commit generated-project developer configuration, game assemblies, + credentials, world data, or other machine-local files. +- Files under `template/` are MIT-0 licensed scaffold material. HeimForge code + outside `template/` is Apache-2.0 licensed. Preserve that licensing boundary. + +## Testing + +During development, prefer targeted tests for the area being changed. + +For changes under `template/`, always run: + +```bash +./scripts/validate-template.sh +``` + +The canonical full HeimForge test suite is: + +```bash +./scripts/test.sh +``` + +Broad, cross-cutting, generator, template, release, or security-sensitive +changes should pass the full suite before completion. + +GitHub Actions also provides a manually dispatched full test suite for hosted +validation with Python and .NET. + +## Pull requests + +Before opening a pull request: + +```bash +git diff --check +``` + +Make sure relevant tests pass and the working tree contains no generated or +machine-local files. + +Use a concise Conventional Commit style title where practical, for example: + +- `feat: add ...` +- `fix: correct ...` +- `docs: clarify ...` +- `test: cover ...` +- `chore: update ...` + +HeimForge uses Release Please, so clear conventional commit history helps +produce meaningful automated releases. + +Pull requests should explain: + +- what changed +- why it changed +- what validation was performed +- whether generated-project behavior or template output changed + +## Reporting bugs and proposing features + +Use the repository issue forms for normal bug reports and feature requests. + +Security vulnerabilities must not be reported through a public issue. Follow +the instructions in `SECURITY.md`. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..ed0f695 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,52 @@ +# Security Policy + +## Supported versions + +Security fixes are maintained for the latest released version of HeimForge and +the current `main` branch. + +Older releases may not receive backported fixes unless explicitly stated. + +## Reporting a vulnerability + +Do not open a public GitHub issue for a suspected security vulnerability. + +Use GitHub's private vulnerability reporting for this repository: + +1. Open the repository on GitHub. +2. Select **Security**. +3. Select **Report a vulnerability**. +4. Provide enough detail to reproduce and assess the issue. + +Useful reports include: + +- the affected HeimForge version or commit +- the affected component or file +- reproduction steps +- the expected and observed behavior +- the potential security impact +- any suggested mitigation, if known + +Do not include live credentials, private keys, access tokens, production server +credentials, or other secrets unless specifically required for coordinated +investigation. + +## Scope + +Security-sensitive areas include, among others: + +- generator path and filesystem safety +- generated-project deployment tooling +- archive/package path handling +- SSH/SFTP deployment behavior +- handling of local configuration and credentials +- GitHub Actions and release automation +- validation boundaries between HeimForge and generated repositories + +Ordinary bugs, documentation issues, feature requests, and project-specific +Valheim gameplay problems should use the normal issue forms instead. + +## Disclosure + +Please allow maintainers reasonable time to investigate and prepare a fix +before publicly disclosing an unresolved vulnerability.