From 73acce9bb5a700e39149a1798304a8d3ddef0e91 Mon Sep 17 00:00:00 2001 From: redcatbaer Date: Sat, 5 Sep 2026 20:34:59 +0200 Subject: [PATCH] #1: Added repo docu. --- CODE_OF_CONDUCT.md | 9 +++++++++ CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++++++++++++ README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ SECURITY.md | 19 +++++++++++++++++++ 4 files changed, 114 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 SECURITY.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..2ddfe61 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,9 @@ +# OpenFastTrace Code of Conduct + +* Treat others with respect. +* Criticize ideas, not people. +* Back up your arguments with facts and reasoning. +* Keep discussions on topic and concise. +* Disagreements are fine — personal attacks are not. +* Help people who ask for it. We were all beginners once. +* Offer solutions, not just complaints. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4f6d585 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ +Thank you for your interest in helping us make the OpenFastTrace Debian package better! + +# Goal of This Document + +This document answers questions potential contributors to the OpenFastTrace Debian package might have before getting started. + +# What This Document Is Not + +For general information about OpenFastTrace (OFT), see the [upstream project](https://github.com/itsallcode/openfasttrace). For information about this package, see the [README](README.md). + +# What Kind of Contributions Can I Make? + +## Contributing Code + +If you want to improve the Debian packaging, build scripts, tests, or design, create a branch from the current `main` branch using [git](https://git-scm.com/) and make your changes there. Then create a pull request for review. Reviewers will ask you to incorporate any findings before merging the change. + +Changes to OpenFastTrace itself belong in the [upstream repository](https://github.com/itsallcode/openfasttrace). + +## AI Assisted Coding + +We accept contributions written with the assistance of AI coding agents. If you rely heavily on AI assistance, include a note in your pull request explaining how you used the AI agent and which parts of the code it generated. Review every line generated by AI before submitting your pull request. + +We **do not accept** contributions submitted directly by AI agents. A real person must always be responsible for submitted code. + +We also will not accept contributions that are clearly generated by AI agents but not labeled as such. + +## Testing + +We are happy if you test the package, especially on Debian-derived platforms that are not covered by our automation. If you find a packaging bug, please open an [issue](https://github.com/itsallcode/openfasttrace-debian-package/issues/new). Include enough information to reproduce it, such as the distribution, version, architecture, package version, command, and output. + +Before submitting a packaging change, run the relevant checks. The full integration test builds the source and binary packages, checks their contents, runs ShellCheck, and validates AppStream metadata: + +```sh +./test-packaging.sh +``` + +## Ideas + +If you have an idea to improve packaging or distribution, open a [feature request](https://github.com/itsallcode/openfasttrace-debian-package/issues/new). + +# Style Guides + +Keep shell scripts compatible with Bash and free of ShellCheck findings. Match the existing Debian packaging conventions and the project's requirement-tracing notation in `doc/` and source comments. We use the principles described in Robert C. Martin's book *Clean Code* as guidance for designing and organizing code. diff --git a/README.md b/README.md new file mode 100644 index 0000000..57ea371 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# OFT logo OpenFastTrace Debian Package + +This repository builds Debian packages for [OpenFastTrace](https://github.com/itsallcode/openfasttrace) (OFT), a requirement tracing suite. OFT keeps track of whether you implemented everything planned in your specifications and identifies obsolete parts of a product. + +[![Build Debian package](https://github.com/itsallcode/openfasttrace-debian-package/actions/workflows/build.yml/badge.svg)](https://github.com/itsallcode/openfasttrace-debian-package/actions/workflows/build.yml) + +## Getting the Package + +Pre-built source and binary packages are available from the [GitHub releases](https://github.com/itsallcode/openfasttrace-debian-package/releases). Install the binary package with its Java runtime dependency: + +```sh +sudo apt install ./openfasttrace_-1_all.deb +``` + +Run OpenFastTrace with: + +```sh +oft --help +``` + +For OFT usage, including command-line options and requirement notation, see the upstream [user guide](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide/user_guide.md). + +## Building a Package + +On Debian or a derived distribution, install the tools listed by the precondition check, then build a source package and its binary package for an upstream release: + +```sh +./check-preconditions.sh +./create-source-package.sh +./create-binary-package.sh +``` + +The resulting artifacts are placed in `out/`. The scripts download the specified OpenFastTrace source release, incorporate this repository's `debian/` packaging metadata, and build the package. + +## Project Information + +* [OpenFastTrace upstream project](https://github.com/itsallcode/openfasttrace) +* [Upstream user guide](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide/user_guide.md) +* [Package design](doc/design.md) +* [System requirements](doc/system_requirements.md) +* [Security policy](SECURITY.md) +* [Contributing guide](CONTRIBUTING.md) +* [Code of conduct](CODE_OF_CONDUCT.md) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..954cc90 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,19 @@ +# Security Policy + +We value the work of security researchers and users who help us keep the OpenFastTrace Debian package secure. Thank you for your support! + +## Supported Versions + +We provide security updates for the latest package release. Security fixes to OpenFastTrace itself follow the [upstream project lifecycle](https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide/project_lifecycle.md). + +## Reporting a Vulnerability + +If you discover a potential security issue in this packaging repository or its published packages, please report it privately via [GitHub Security Advisories](https://github.com/itsallcode/openfasttrace-debian-package/security/advisories/new). For a vulnerability in OpenFastTrace itself, use the [upstream security reporting channel](https://github.com/itsallcode/openfasttrace/security/advisories/new). + +We follow coordinated disclosure and aim to: + +- **Respond** to your report within 48 hours. +- **Provide a fix** within 30 days. +- **Disclose** the details publicly once a fix is available and users have had time to update. + +While we don't offer bug bounties, we'd be happy to publicly acknowledge your contribution in the advisory.