From ae2476e2ab9bb965eb556d301f075d10ed932e38 Mon Sep 17 00:00:00 2001 From: Georgios Chatoutsidis Date: Wed, 10 Jun 2026 15:34:35 +0300 Subject: [PATCH] Add documentation for public release readiness, including issue and pull request templates, contribution guidelines, security policy, and changelog --- .github/ISSUE_TEMPLATE/bug_report.md | 44 ++++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 29 ++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 22 +++++++++ CHANGELOG.md | 54 +++++++++++++++++++++++ CODE_OF_CONDUCT.md | 23 ++++++++++ CONTRIBUTING.md | 48 ++++++++++++++++++++ README.md | 50 +++++++++++++++++++-- SECURITY.md | 21 +++++++++ docs/SRS.md | 10 ++--- 9 files changed, 293 insertions(+), 8 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..0a784d2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,44 @@ +--- +name: Bug report +about: Report a reproducible XCSKit problem +title: "" +labels: bug +assignees: "" +--- + +## Description + +Describe the problem clearly. + +## Reproduction + +Steps or a minimal Swift snippet: + +```swift + +``` + +Minimal `.xcstrings` input if relevant: + +```json + +``` + +## Expected Behavior + +What did you expect to happen? + +## Actual Behavior + +What happened instead? + +## Environment + +- XCSKit version or commit: +- Swift version: +- Xcode version: +- OS: + +## Additional Context + +Add logs, stack traces, or links when useful. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..06bedd7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,29 @@ +--- +name: Feature request +about: Suggest an improvement or new capability +title: "" +labels: enhancement +assignees: "" +--- + +## Problem + +What user or developer problem would this solve? + +## Proposed Solution + +Describe the API, behavior, or documentation change you would like. + +## Alternatives Considered + +What other approaches did you consider? + +## Scope + +- Affected module or modules: +- Does this require an SRS update? Yes / No / Unsure +- Does this require new tests? Yes / No / Unsure + +## Additional Context + +Add examples, catalog shapes, or links when useful. \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8da902e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## Summary + +- + +## Type of Change + +- [ ] Bug fix +- [ ] Feature +- [ ] Documentation +- [ ] Tests +- [ ] CI or repository maintenance + +## Requirements and Tests + +- [ ] I updated `docs/SRS.md` if committed behavior changed. +- [ ] I added or updated requirement-level tests when applicable. +- [ ] `swift build` passes locally. +- [ ] `swift test` passes locally. + +## Notes + +Include any compatibility notes, migration details, or follow-up work. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..f36ced4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,54 @@ +# Changelog + +All notable changes to XCSKit are documented in this file. + +The project follows semantic versioning while it is pre-1.0. Public API changes may still occur before a stable 1.0 baseline. + +## Unreleased + +### Added + +- MIT License file. +- Public release readiness documentation, including contribution, security, conduct, changelog, issue template, and pull request template guidance. +- README installation instructions, requirements, license, and public API status notes. + +### Changed + +- Swift CI now runs on pull requests, pushes to `main`, and manual dispatches. +- SRS document control now uses public-facing audience and status language. + +## 0.3.1 + +### Fixed + +- Translation progress calculations and related documentation updates. + +## 0.3.0 + +### Changed + +- Adjusted Swift CI trigger behavior. + +## 0.2.2 + +### Fixed + +- Fixed translator patch generation behavior. + +## 0.2.1 + +### Changed + +- Moved parser and shared model implementation toward `Codable`-based decoding. + +## 0.2.0 + +### Added + +- Added the XCSAnalytics module. + +## 0.1.0 + +### Added + +- Initial tagged baseline for XCSKit. \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ead4958 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,23 @@ +# Code of Conduct + +XCSKit aims to be a respectful, practical, and welcoming project for people working on localization tooling. + +## Expected Behavior + +- Be respectful and constructive in issues, pull requests, and reviews. +- Assume good intent, especially when discussing bugs or design tradeoffs. +- Keep feedback focused on the work and its impact on users. +- Make room for different experience levels with Swift, localization, and open source. + +## Unacceptable Behavior + +- Harassment, threats, personal attacks, or sustained disruption. +- Discriminatory language or conduct. +- Publishing private information without permission. +- Sharing sensitive security details publicly before a coordinated disclosure. + +## Enforcement + +Project maintainers may moderate, edit, or remove comments and may restrict participation when behavior harms the project or its contributors. + +If you need to report conduct concerns, contact the maintainer privately with relevant context and links. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b88aa24 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to XCSKit + +Thanks for taking the time to improve XCSKit. This project is a Swift Package for parsing, validating, translating, writing, and analyzing Apple's `.xcstrings` catalogs. + +## Development Setup + +Requirements: + +- Swift 6.3 +- Swift Package Manager +- macOS for the currently verified CI environment + +From the repository root, use: + +```bash +swift build +swift test +``` + +## Branches and Pull Requests + +- Create focused branches such as `docs/public-release-readiness`, `fix/parser-error-paths`, or `feature/validator-findings`. +- Keep pull requests scoped to one behavior change, documentation change, or release task. +- Include tests for behavior changes and update documentation when public APIs or requirements change. +- Run `swift build` and `swift test` before opening or updating a pull request. + +## Requirements and Tests + +The public requirements baseline lives in [docs/SRS.md](docs/SRS.md). Requirement-level tests use matching IDs: + +- Requirement `VAL-004` maps to `Tests/XCSKitTests/VAL_004.swift`. +- Requirement `TRN-003` maps to `Tests/XCSKitTests/TRN_003.swift`. +- Requirement `WRT-005` maps to `Tests/XCSKitTests/WRT_005.swift`. + +When adding or changing committed requirements, update both the SRS requirement text and the requirement-to-test mapping table. + +## Style Notes + +- Prefer small, explicit public APIs with descriptive type and method names. +- Keep parser, validator, translator, writer, analytics, and core-model responsibilities separated. +- Avoid adding runtime package dependencies unless the project explicitly decides to expand scope. +- Preserve `.xcstrings` values and placeholder tokens exactly unless a documented writer operation intentionally changes them. + +## Reporting Issues + +For bugs, include the Swift version, OS, package version or commit, a minimal catalog sample when possible, expected behavior, and actual behavior. + +For sensitive security reports, follow [SECURITY.md](SECURITY.md) instead of opening a public issue. \ No newline at end of file diff --git a/README.md b/README.md index e0bd6de..1fa0b5f 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,43 @@ XCSKit is a Swift Package for working with Apple's `.xcstrings` string catalog files through a layered set of modules. -The repository includes a working parser implementation, a representative sample catalog, an automated test suite, and a formal software requirements specification that now tracks the next v2 increment. +The repository includes a working parser implementation, a representative sample catalog, an automated test suite, and a public software requirements specification that tracks implemented behavior and near-term roadmap items. + +## Installation + +Add XCSKit to a Swift Package Manager project with the repository URL: + +```swift +dependencies: [ + .package(url: "https://github.com/chatoutsidis/XCSKit.git", from: "0.3.1") +] +``` + +Then add whichever product you need to your target dependencies: + +```swift +.target( + name: "YourTarget", + dependencies: [ + .product(name: "XCSParser", package: "XCSKit"), + .product(name: "XCSValidator", package: "XCSKit"), + .product(name: "XCSWriter", package: "XCSKit") + ] +) +``` + +In Xcode, use **File > Add Package Dependencies...**, enter the repository URL, and select the products your app or tool imports. Use `XCSKit` when you want the umbrella import, or choose individual products for narrower module boundaries. + +## Requirements + +| Requirement | Current Support | +|-------------------------|--------------------------------| +| Swift tools | 6.3 | +| Package manager | Swift Package Manager | +| Runtime dependencies | None | +| Verified CI environment | macOS 15 runner with Swift 6.3 | + +The package is Foundation-based and intended for local tooling, server-side utilities, and Apple-platform build workflows. Broader platform minimums should be treated as uncommitted until they are added to the package manifest and CI matrix. ## Goals @@ -264,6 +300,13 @@ Continuous integration: - `XCSWriter` API guide: [docs/modules/XCSWriter.md](docs/modules/XCSWriter.md) - `XCSAnalytics` API guide: [docs/modules/XCSAnalytics.md](docs/modules/XCSAnalytics.md) - `XCSKit` umbrella guide: [docs/modules/XCSKit.md](docs/modules/XCSKit.md) +- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md) +- Security policy: [SECURITY.md](SECURITY.md) +- Release notes: [CHANGELOG.md](CHANGELOG.md) + +## License + +XCSKit is available under the MIT License. See [LICENSE](LICENSE) for details. ## Status @@ -271,7 +314,8 @@ Current repository status: - Package manifest is present in [Package.swift](Package.swift) and now exposes parser, core, validator, translator, and writer modules. - Parser implementation supports core `.xcstrings` parsing, typed lookup helpers, and forward-compatible extraction-state metadata. -- Validation, translation orchestration, and writing are implemented as separate layers over the shared catalog model. -- The checked-in tests cover parsing, validation, placeholder preservation, representative variant behavior, and the new separation layers. +- Validation, translation orchestration, writing, and analytics are implemented as separate layers over the shared catalog model. +- The checked-in tests cover parsing, validation, placeholder preservation, representative variant behavior, translation workflows, writer behavior, analytics, and non-functional requirements. +- The public API is still pre-1.0. Minor releases may refine API names or module boundaries before a stable 1.0 baseline. If you are contributing implementation work, start with [docs/SRS.md](docs/SRS.md). It defines the committed v1 requirements, validation behavior, non-functional constraints, and planned verification coverage. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..db5d37f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,21 @@ +# Security Policy + +## Supported Versions + +XCSKit is currently pre-1.0. Security fixes are expected to land on the default branch first and be included in the next tagged release. + +## Reporting a Vulnerability + +Please do not open a public issue for a vulnerability report. + +Use GitHub private vulnerability reporting for this repository if it is enabled. If private reporting is not yet available, contact the maintainer through a private channel first and include only enough information to establish contact. + +Helpful report details include: + +- Affected XCSKit version or commit +- Swift version and operating system +- Minimal `.xcstrings` input or API sequence needed to reproduce the issue +- Expected and observed impact +- Whether the issue is already public + +The maintainer will acknowledge reports as soon as practical, investigate reproducibility and impact, and coordinate disclosure timing before public details are published. \ No newline at end of file diff --git a/docs/SRS.md b/docs/SRS.md index f9a78dc..c522f05 100644 --- a/docs/SRS.md +++ b/docs/SRS.md @@ -4,16 +4,16 @@ - Product: XCSKit - Type: Swift Package library -- Version: Draft v2.2 -- Status: Working draft for implementation and verification -- Date: 2026-04-17 -- Intended audience: Internal engineering +- Version: v2.2 public baseline +- Status: Public requirements baseline for implemented behavior and near-term roadmap +- Date: 2026-06-10 +- Intended audience: Developers and contributors ## 2. Purpose and Scope XCSKit is a Swift Package for working with Apple's `.xcstrings` string catalog files through a layered set of modules. The package centers on shared typed domain models and currently includes a parse-only parser, a non-mutating validator, a provider-driven translator, a writer for serialization and patch-oriented persistence, and a read-only analytics module for reporting and statistics. This SRS defines the committed requirements for the parser baseline and the implemented validator, translator, writer, and analytics capabilities. -As of the date of this revision, the repository contains a working implementation of the parser baseline, initial validator/translator/writer layers, automated tests for the committed behavior, and a representative sample catalog. Accordingly, this document serves both as a description of committed behavior and as the requirements baseline for the next increment. +As of the date of this revision, the repository contains a working implementation of the parser baseline, validator, translator, writer, and analytics layers, automated tests for the committed behavior, and a representative sample catalog. Accordingly, this document serves both as a public description of committed behavior and as the requirements baseline for the next increment. ## 3. Product Overview