{"id":31847904,"url":"https://github.com/wireapp/wire-docs","last_synced_at":"2025-10-12T09:58:30.275Z","repository":{"id":272977688,"uuid":"916144700","full_name":"wireapp/wire-docs","owner":"wireapp","description":" Wire Documentation","archived":false,"fork":false,"pushed_at":"2025-10-02T10:56:44.000Z","size":14867,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-02T12:38:29.127Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.wire.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wireapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-13T14:40:58.000Z","updated_at":"2025-10-02T10:56:50.000Z","dependencies_parsed_at":"2025-02-28T15:40:38.464Z","dependency_job_id":"40ad3a97-9168-49f1-84f3-43a0a12ece2c","html_url":"https://github.com/wireapp/wire-docs","commit_stats":null,"previous_names":["wireapp/wire-docs"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wireapp/wire-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireapp%2Fwire-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireapp%2Fwire-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireapp%2Fwire-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireapp%2Fwire-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wireapp","download_url":"https://codeload.github.com/wireapp/wire-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wireapp%2Fwire-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010951,"owners_count":26084841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-12T09:58:26.902Z","updated_at":"2025-10-12T09:58:30.270Z","avatar_url":"https://github.com/wireapp.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Wire-documents-structure\n\nWire documentation is hosted on \u003chttps://docs.wire.com\u003e. This project uses MkDocs as its documentation generator.\n\n## Structure of the repository\n### src Directory\nContains the source files and directories for the documentation. The `src` directory has been migrated from the [wire-server docs](https://github.com/wireapp/wire-server/tree/develop/docs). The previous version used Sphinx, so we converted it to Markdown and adapted it for MkDocs. See `build/old-docs.md` for the migration process.\n\n### External Pages (Git Submodules)\nWe import documentation pages from the backend repository [wire-server](https://github.com/wireapp/wire-server/tree/develop). Many files currently reference wire-server, which you can identify using:\n\n```bash\nfind . -type l -printf '%p -\u003e %l\\n' | grep './src'\n```\n\n#### Submodule Management\n\n**Fetch latest updates from wire-server:**\n```bash\ngit submodule update --remote --checkout --depth 1 -- wire-server\n```\n*Note: Only run this command when the remote repository has new changes.*\n\n**Checkout a specific commit:**\n```bash\ncd wire-server \u0026\u0026 git fetch --depth=1 origin \u003ccommit-id\u003e \u0026\u0026 git checkout \u003ccommit-id\u003e\n```\n\n**Verify submodule status:**\n```bash\ngit submodule status\n```\n\n**Update changelog (optional):**\nTo optionally update the src/changelog/README.md based on the new changelog.md, run the following command:\n\n``` bash\nrm src/changelog/README.md \u0026\u0026 \\\ngrep '^# ' src/changelog/changelog.md | \\\nsed 's/^# //' | while IFS= read -r heading; \\\ndo anchor=$(echo \"$heading\" | sed -E 's/^\\[?([0-9-]+)\\]? *(\\(([^)]+)\\)|# *([0-9]+))$/\\1-\\3\\4/' | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g;s/\\.//g'); echo \"* [$heading](changelog.md#$anchor)\"; done \u003e src/changelog/README.md\n```\n\n### build Directory\nContains scripts used by the Makefile to support different build use cases. The system is designed to run one build process at a time. All local targets use a temporary directory (stored in `.tmpdir` file) for building and serving changes due to git operations required by tools like `mike` for MkDocs.\n\n## Prerequisites\n\n- make\n- nix-shell\n- git\n- rsync\n- Docker (optional) - for building Docker images when testing without nix-shell\n\n## Makefile Targets\n\n### `make current`\nRuns the documentation site locally using Mike (MkDocs plugin) for the `current` branch only. Current changes appear under the `latest` as the version name. Hosted at `0.0.0.0:8000`.\n\n### `make run`\nServes the documentation site locally by building the current branch as static web pages, then hosts a web server using Python's HTTP module. This allows you to preview how the documentation will appear when hosted for the current branch under `latest` version. Hosted at `0.0.0.0:8000`.\n\n### `make archive`\nArchives the processed web pages for the current branch from the GitHub `gh-pages` branch (created by `make build`). Output is generated in the main directory as `wire-docs.tar.gz`.\n\n### `make build`\nUsed by `run` and `archive` targets to build the current branch. Attempts to identify the version name for the environment. In GitHub environments, it identifies a suitable name for the version being built, based on the type of trigger event, such as a Pull Request, a Push, or the creation of a Tag.\n\n### `make docker` *(Experimental)*\nBuilds a Docker image for the documentation using the repository's Dockerfile. Uses Python's `mike` module to host documents (experimental - not the standard Python HTTP module). For testing current changes, use `make run` or `make current` instead.\n\nTo test the Docker image locally:\n```bash\ndocker run -d -p 8000:8000 --restart=always --health-cmd=\"curl --fail http://localhost:8000 || exit 1\" --health-interval=30s --health-retries=3 --health-timeout=5s wire-docs\n```\n\n### `make clean`\nCleans up generated tar files and temporary directories from the build process.\n\n### Verbose Mode\nFor increased verbosity in make commands:\n```bash\nmake SHELL=\"/bin/bash -x\" target\n```\n\n## GitHub Actions for Build and Deployment\n\n```mermaid\n  graph TD\n\n    %% Triggers\n    PR[Pull Request to main] --\u003e |triggers| BuildWorkflow\n    PushMain[Push to main Branch] --\u003e |triggers| DeployWorkflow\n    CreateRelease[Create Release] --\u003e |triggers| ReleaseWorkflow\n    TestEnvironment[Push to test-dev Branch] --\u003e |triggers| TestWorkflow\n\n    %% Styling\n    classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n    classDef action fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px\n\n    class BuildWorkflow,DeployWorkflow,ReleaseWorkflow,TestWorkflow workflow\n    class PR,PushMain,CreateRelease,TestEnvironment action\n\n```\n\nThe repository includes four automated builds:\n\n### 1. [Build Test](.github/workflows/build.yaml)\nRuns `make build` to verify MkDocs build structure for each pull request.\n\n```mermaid\n  graph TD\n    %% Build Workflow (PR)\n    BuildWorkflow[Build Workflow\u003cbr/\u003ebuild.yaml] --\u003e |runs| BuildMake[make build]\n    BuildMake --\u003e |verifies| DocStructure[Documentation Structure]\n    DocStructure --\u003e |identifies| NavIssues[Navigation/Markdown Issues]\n\n    %% Styling\n    classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px\n    classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n\n    class BuildWorkflow workflow\n    class DocStructure,NavIssues output\n\n```\n\n\n### 2. [Prod Env Latest Build and Deploy to S3](.github/workflows/deploy.yaml)\nRuns `make archive` on every push to the main branch as the `latest` version. Cleans old `latest` documents before uploading to ensure the S3 bucket matches the main branch state. Maintains `versions.json` (tracking all document versions) without overwriting, keeping it synchronized with the latest version with commit as an alias.\n\n```mermaid\n  graph TD\n    %% Deploy Workflow (Push to Main)\n    DeployWorkflow[Deploy Workflow\u003cbr/\u003edeploy.yaml] --\u003e |runs| ArchiveMake[make archive]\n    ArchiveMake --\u003e |creates| LatestVersion[latest Version]\n    LatestVersion --\u003e |cleans old| OldDocs[Old latest Documents]\n    LatestVersion --\u003e |pushes to| S3Latest[S3 Bucket - Latest]\n    LatestVersion --\u003e |maintains| VersionsJSON[versions.json]\n\n    %% Styling\n    classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px\n    classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n\n    class DeployWorkflow workflow\n    class LatestVersion,S3Latest,VersionsJSON,OldDocs output\n\n```\n\n### 3. [Build, Deploy and Release Artifact](.github/workflows/release.yaml)\nRuns `make archive` when creating new releases, using the git tag (ref_name) as the version. Follows the same cleaning and S3 management process as the production deployment. Creates a release asset equivalent to the `make archive` output for that git tag.\n\n```mermaid\n  graph TD\n    %% Release Workflow (Create Release)\n    ReleaseWorkflow[Release Workflow\u003cbr/\u003erelease.yaml] --\u003e |runs| ArchiveMakeRelease[make archive]\n    ArchiveMakeRelease --\u003e |creates| TaggedVersion[Tagged Version]\n    TaggedVersion --\u003e |pushes to| S3Tag[S3 Bucket - ref_name]\n    TaggedVersion --\u003e |maintains| VersionsJSON[versions.json]\n    TaggedVersion --\u003e |cleans old| OldDocs[Old ref_name Documents]\n    TaggedVersion --\u003e |creates| ReleaseAsset[Release Asset \u003cbr/\u003e wire-docs-ref_name.tar.gz]\n\n\n    %% Styling\n    classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px\n    classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n\n    class ReleaseWorkflow workflow\n    class TaggedVersion,ReleaseAsset,S3Tag,VersionsJSON,OldDocs output\n\n```\n\n### 4. [Test Environment Build and S3 Deploy](.github/workflows/test.yaml)\nTests the above operations in a staging bucket environment.\n\n```mermaid\n  graph TD\n    %% Test Workflow\n    TestWorkflow[Test Workflow\u003cbr/\u003etest.yaml]\n    TestWorkflow --\u003e |runs| TestArchive[make archive]\n    TestArchive --\u003e |creates| LatestVersion[latest Version]\n    LatestVersion --\u003e |cleans old| OldDocs[Old latest Documents Staging]\n    LatestVersion --\u003e |pushes to| S3Staging[S3 Staging Bucket - Latest]\n    LatestVersion --\u003e |maintains| VersionsJSON[Staging versions.json]\n\n    %% Styling\n    classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px\n    classDef workflow fill:#f3e5f5,stroke:#4a148c,stroke-width:2px\n\n    class TestWorkflow workflow\n    class LatestVersion,S3Staging,VersionsJSON,OldDocs output\n```\n\n## Versioning System\n\n### Version Format\nVersion numbers follow a three-part format: **A.B.C**\n\n- **A (Major Version)**: Indicates the minimum API contract version supported by this release. When this increases, it signals deprecation of older API contract versions. For example, V5.0.0 supports API V5 and newer. Major versions may include breaking changes such as database migrations or backend service structure changes.\n\n- **B (Feature Iteration)**: Reflects feature updates that don't affect API contract compatibility or introduce breaking changes. For example, V5.1.0 supports API V5 and newer while adding new features or improvements without altering compatibility.\n\n- **C (Fix Iteration)**: Incremented for bug fixes or security updates that don’t introduce new features or modify compatibility. Fix iterations contain no breaking changes.\n\n**Note**: The first release, `v0.0.0`, indicates that the documentation supports all API versions.\n\n## Version and Tag Relationship\n\n## Relationship Between Versions and Tags:\n- We provide multiple documentation versions, with each version corresponding to a specific release in the wire-docs repository.\n\n- Releases are based on Git tags, which mark a specific point in your repository's history.\n\n- Once a version or tag is released, it becomes immutable. Future updates require creating new versions—no further edits are permitted on existing tags.\n\n-The latest version is regularly updated based on commits to the main branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwireapp%2Fwire-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwireapp%2Fwire-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwireapp%2Fwire-docs/lists"}