Added lifecycle information and a security policy. (#579)

#579: Added lifecycle information and a security policy.

Author: redcatbear

AGENTS.md

@@ -109,7 +109,7 @@ Needs: impl, utest
 - **Key Resources**:
   - `README.md`: General overview.
   - `doc/developer_guide.md`: Detailed build and internal info.
-  - `doc/user_guide.md`: Comprehensive tool usage.
+  - `doc/user_guide/user_guide.md`: Comprehensive tool usage.
   - `CONTRIBUTING.md`: Human-AI collaboration guidelines.
   - `doc/spec/system_requirements.md`: System requirements specification.
   - `doc/spec/design.md`: High-level design documentation.

CONTRIBUTING.md

@@ -29,7 +29,7 @@ If you find a bug, please let us know by writing an [issue ticket](https://githu
 If you are a programmer, a code contribution in form of an automatic unit test case would be most appreciated, since this will make reproduction of the issue easier and prevent future regressions.
 
 ## Contributing to the User Guide
-Maybe you are good at explaining how to use OFT to end users? Help us improve the [user guide](doc/user_guide.md)!
+Maybe you are good at explaining how to use OFT to end users? Help us improve the [user guide](doc/user_guide/user_guide.md)!
 
 ## Translations
 We plan to make OFT multilingual. If you want to provide a translation, feel free to contact us. Messages in OFT and the user guide are prime candidates for translation.

README.md

@@ -4,7 +4,7 @@
 
 OpenFastTrace (short OFT) is a requirement tracing suite. Requirement tracing keeps track of whether you actually implemented everything you planned to in your specifications. It also identifies obsolete parts of your product and helps you to get rid of them.
 
-You can learn more about requirement tracing and how to use OpenFastTrace in the [user guide](doc/user_guide.md).
+You can learn more about requirement tracing and how to use OpenFastTrace in the [user guide](doc/user_guide/user_guide.md).
 
 Below you see a screenshot of an HTML tracing report where OFT traces itself. You see a summary followed by a detail view of the traced requirements. 
 
@@ -31,10 +31,13 @@ Sonarcloud status:
 
 **User Guides and Tools**
 
-* [📖 User Guide](doc/user_guide.md)
+* [📖 User Guide](doc/user_guide/user_guide.md)
 * [🔌 Extending OpenFastTrace With Plugins](doc/plugins.md)
 * [💲 Command Line Usage](core/src/main/resources/usage.txt)
 * [🛠 IntelliJ Plugin (PyCharm, Clion, etc.)](https://github.com/itsallcode/openfasttrace-intellij-plugin)
+* [🤖 Agent Skills](.agents/skills)
+* [🛡️ Security Policy](SECURITY.md)
+* [♻️ Project Lifecycle and Deprecations](doc/user_guide/project_lifecycle.md)
 
 **News and Discussions**
 
@@ -68,7 +71,7 @@ Sonarcloud status:
 
 If you want to use OFT, you have the choice between using it as part of your build process — typically with Maven or Gradle. Or you can run OFT from the command line.
 
-Check the [user guide](doc/user_guide.md) for detailed information on how to use OpenFastTrack.
+Check the [user guide](doc/user_guide/user_guide.md) for detailed information on how to use OpenFastTrack.
 
 ## Getting OpenFastTrace
 
@@ -110,7 +113,7 @@ java -jar product/target/openfasttrace-4.2.0.jar trace /path/to/directory/being/
 
 If you want to run OFT automatically as part of a continuous build, we recommend using our plugins for [Gradle](https://github.com/itsallcode/openfasttrace-gradle) and [Maven](https://github.com/itsallcode/openfasttrace-maven-plugin).
 
-For more details about how to run OFT please consult the [user guide](doc/user_guide.md).
+For more details about how to run OFT please consult the [user guide](doc/user_guide/user_guide.md).
 
 ### Download and Execute in Continuous Integration
 

SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+We value the work of security researchers and users who help us keep OpenFastTrace secure. Thank you for your support!
+
+## Supported Versions
+
+We provide security updates for the latest major version. For a detailed overview of supported versions and End-of-Life (EoL) dates, please see our [Project Lifecycle](doc/user_guide/project_lifecycle.md).
+
+## Reporting a Vulnerability
+
+If you discover a potential security issue, please report it privately via [GitHub Security Advisories](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.

doc/changes/changes.md

@@ -1,5 +1,6 @@
 # Changes
 
+* [4.10.0](changes_4.10.0.md)
 * [4.9.0](changes_4.9.0.md)
 * [4.8.0](changes_4.8.0.md)
 * [4.7.0](changes_4.7.0.md)

doc/changes/changes_4.0.1.md

@@ -4,7 +4,7 @@ Code name: Allow numbers after dots in specification item names
 
 ## Summary
 
-This release allows using specification item names with dots `.` followed by numbers, e.g. `req~SR.AB.1.1.1~1`. We also updated the relevant [section in the user guide](../user_guide.md#specification-item-name). Thanks to [@RobertZickler](https://github.com/RobertZickler) for reporting this!
+This release allows using specification item names with dots `.` followed by numbers, e.g. `req~SR.AB.1.1.1~1`. We also updated the relevant [section in the user guide](../user_guide/user_guide.md#specification-item-name). Thanks to [@RobertZickler](https://github.com/RobertZickler) for reporting this!
 
 ## Bugfixes
 

doc/user_guide/project_lifecycle.md

@@ -0,0 +1,48 @@
+# Project Lifecycle
+
+This is a free and open-source project. Updates are publicly available and free of charge.
+
+Feature, documentation, bugfix and security updates are always provided with the latest release.
+
+## End of Life
+
+This project uses [semantic versioning](https://semver.org/). Versions with the same major version are guaranteed to be backward-compatible to previous versions with that major version.
+
+Minor version updates add features that do not break compatibility and do not change hardware or software environment requirements beyond reasonable update rules. Fix versions only resolve bugs and / or add security updates.
+
+| Version line | First release | End of support | Java version |
+|--------------|---------------|----------------|--------------|
+| 0.x.y        | 2017-08-13    | 2018-06-30     | 8            |
+| 1.x.y        | 2018-06-30    | 2018-10-13     | 8            |
+| 2.x.y        | 2018-10-13    | 2020-04-21     | 8            |
+| 3.x.y        | 2020-04-21    | 2024-06-03     | 11           |
+| 4.x.y        | 2024-06-03    | 2027-10-01     | 17           |
+| 5.x.y        | 2027-10-01    | 2029-12-01     | 21           |
+
+We are synchronizing the EoL with the [Temurin LTS release support](https://adoptium.net/support/). Our strategy is to take a Java version that is mature and stable and long enough out to be available on the majority of platforms and machines and then support it as long as the Temurin project supports the JRE. This way users don't need the latest top-of-the-line installations to run OFT.
+
+## Planned Deprecations and Removals
+
+### Features Scheduled for Removal in OFT 5.0.0
+
+The **SpecObject** format is a legacy from ReqM2. This includes importer, exporter and `aspec` reporter. It lacks the clear structure of OFT's specification item trace model and is not very consistent. Also, JSON is now a more popular base format than XML, that's why we will replace the SpecObject format with OFT's own interchange format.
+
+Switch from the SpecObject format to `.oftx.json` when you want to aggregate and exchange specification documents between projects. Generate `.oftr.json` reports instead of `aspec`.
+
+The `.oftx.json` exchange format and `.oftr.json` report format will be available no later than September 30, 2026. SpecObject will then be deprecated and remain supported throughout OFT 4.x. The SpecObject importer, exporter, and aspec reporter will be removed in OFT 5.0.
+
+**Short tags** are another ReqM2 legacy. While this is a little less typing effort, it breaks our rule of writing out specification item IDs. This is inconvenient for text searches. Also, short tags are the only reason why we need per directory configuration. OFT is designed to use auto-detection wherever possible, and this feature works against the auto-detection. We will remove the configuration together with the short tags.
+
+Migrate to OFT's full coverage tags, and you can drop the per-directory tag-import configuration. Short tags will be officially deprecated with OFT 4.10.0.
+
+## Security Updates
+
+Users need to check the [changelog](../changes/changes.md) to stay informed about security updates. You need to install the provided security updates in a timely manner to keep your setup secure. This is also true for any dependencies of this software that do not come bundled. An example is the Java Runtime Environment.
+
+Itsallcode.org provides security updates until the EoL listed above.
+
+Please refer to our [security policy](../../SECURITY.md) for details on coordinated vulnerability disclosure.
+
+### Retaining Updates
+
+Itsallcode.org distributes updates via GitHub releases. Even if the project should be archived, the releases remain accessible for download. Itsallcode.org will keep each security update accessible for at least 10 years.

doc/user_guide.md doc/user_guide/user_guide.mddoc/user_guide.md renamed to doc/user_guide/user_guide.md

@@ -1,4 +1,4 @@
-![oft-logo](../core/src/main/resources/openfasttrace_logo.svg)
+![oft-logo](../../core/src/main/resources/openfasttrace_logo.svg)
 
 # OpenFastTrace (OFT) User Guide
 
@@ -416,7 +416,7 @@ In projects of a certain size you always reach the point where a single team is
 
 One proven way to do this is to use tags. The teams then decide for which specification items with which tags they are responsible.
 
-![Covering selected tags](images/uml/object/obj_multiple_detailed_designs.svg)
+![Covering selected tags](../images/uml/object/obj_multiple_detailed_designs.svg)
 
 In our example it is the job of Andrea the architect to create a system architecture for the system specification coming from Soeren. Andrea defines a set of components which communicate with each other through well-defined, minimal interfaces. Each component is designed so that it can be independently developed and tested. Only an integration test is later necessary to prove that the components work together as designed. You tag each architectural requirement with the names of the affected components.
 
@@ -1147,7 +1147,7 @@ and the requirement type with the element `<doctype>`.
 
 If you are a software developer planning to integrate OFT into one of your programs or scripts, you will probably want to use the OFT API.
 
-Below you find a few short examples of how to use the OFT API. For details check the JavaDoc documentation of the interface [org.itsallcode.openfasttrace.core.Oft](../core/src/main/java/org/itsallcode/openfasttrace/core/Oft.java) in the source code.
+Below you find a few short examples of how to use the OFT API. For details check the JavaDoc documentation of the interface [org.itsallcode.openfasttrace.core.Oft](../../core/src/main/java/org/itsallcode/openfasttrace/core/Oft.java) in the source code.
 
 ### Using OFT From Java
 
@@ -1258,9 +1258,9 @@ oft.reportToStdOut(trace);
 
 Import, export and report each have an overloaded variant that can be configured using the following classes
 
-* [org.itsallcode.openfasttrace.api.importer.ImportSettings](../api/src/main/java/org/itsallcode/openfasttrace/api/importer/ImportSettings.java)
-* [org.itsallcode.openfasttrace.core.ExportSettings](../core/src/main/java/org/itsallcode/openfasttrace/core/ExportSettings.java)
-* [org.itsallcode.openfasttrace.api.ReportSettings](../api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java)
+* [org.itsallcode.openfasttrace.api.importer.ImportSettings](../../api/src/main/java/org/itsallcode/openfasttrace/api/importer/ImportSettings.java)
+* [org.itsallcode.openfasttrace.core.ExportSettings](../../core/src/main/java/org/itsallcode/openfasttrace/core/ExportSettings.java)
+* [org.itsallcode.openfasttrace.api.ReportSettings](../../api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java)
 
 Each of those classes comes with a builder which is called like this: