|
| 1 | +# CLAUDE.md - Eclipse Che Documentation |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +Eclipse Che documentation built with **Antora** and **AsciiDoc**. Published at https://www.eclipse.org/che/docs/. |
| 6 | + |
| 7 | +## Build Commands |
| 8 | + |
| 9 | +```bash |
| 10 | +# Local preview (requires container tools) |
| 11 | +./tools/preview.sh |
| 12 | + |
| 13 | +# Build documentation site |
| 14 | +antora generate antora-playbook-for-development.yml |
| 15 | + |
| 16 | +# Build and verify container |
| 17 | +./tools/build-and-verify-container.sh |
| 18 | + |
| 19 | +# Validate language (Vale) on changed files |
| 20 | +./tools/validate_language_changes.sh |
| 21 | + |
| 22 | +# Detect unused/orphaned content |
| 23 | +./tools/detect_unused_content.sh |
| 24 | + |
| 25 | +# Validate AsciiDoc attributes |
| 26 | +./tools/validate_attributes_processing.sh |
| 27 | + |
| 28 | +# Verify cross-references |
| 29 | +./tools/verify_xrefs.sh |
| 30 | +``` |
| 31 | + |
| 32 | +## Repository Structure |
| 33 | + |
| 34 | +``` |
| 35 | +modules/ # Content modules |
| 36 | + administration-guide/ # Deployment, configuration, management |
| 37 | + end-user-guide/ # User-facing features |
| 38 | + extensions/ # Extension development |
| 39 | + glossary/ # Terminology |
| 40 | + hosted-che/ # Hosted solution docs |
| 41 | + overview/ # Introduction and overview |
| 42 | + <module>/ |
| 43 | + pages/ # Full navigable pages |
| 44 | + partials/ # Reusable content snippets |
| 45 | + images/ # Module-specific images |
| 46 | + examples/ # Code/content examples |
| 47 | + nav.adoc # Navigation structure |
| 48 | +
|
| 49 | +tools/ # Build and validation scripts |
| 50 | +supplemental-ui/ # Custom UI overrides (CSS, fonts, images) |
| 51 | +templates/ # Content templates (assembly, concept, procedure, reference) |
| 52 | +extensions/ # Antora extensions (PDF, htmltest) |
| 53 | +.github/workflows/ # CI/CD (10 workflows) |
| 54 | +``` |
| 55 | + |
| 56 | +## Key Configuration Files |
| 57 | + |
| 58 | +- `antora.yml` - Component descriptor, version, 200+ AsciiDoc attributes |
| 59 | +- `antora-playbook-for-development.yml` - Build playbook for local/PR builds |
| 60 | +- `antora-assembler.yml` - PDF generation playbook |
| 61 | +- `.htmltest.yml` - Link validation config |
| 62 | +- `.vale.ini` - Language/style validation config |
| 63 | +- `Containerfile` - Build container definition |
| 64 | +- `devfile.yaml` - Eclipse Che workspace definition |
| 65 | + |
| 66 | +## Branch Strategy |
| 67 | + |
| 68 | +- `main` - Next version development (currently targets 7.115.x) |
| 69 | +- `7.115.x`, `7.113.x`, etc. - Stable release branches |
| 70 | +- `publication` - Published documentation (read-only) |
| 71 | +- Backport branches: `backport-<PR#>-to-<version>` (e.g., `backport-3017-to-7.113.x`) |
| 72 | + |
| 73 | +### Remotes |
| 74 | + |
| 75 | +- `origin` - User's fork (e.g., `gtrivedi88/che-docs`) |
| 76 | +- `upstream` - Canonical repo (`eclipse-che/che-docs`) |
| 77 | + |
| 78 | +## Backporting Workflow |
| 79 | + |
| 80 | +1. Ensure the PR is merged to `main` first |
| 81 | +2. Fetch upstream and checkout the target release branch: |
| 82 | + ```bash |
| 83 | + git fetch upstream <branch> |
| 84 | + git checkout upstream/<branch> |
| 85 | + git checkout -b backport-<PR#>-to-<branch> |
| 86 | + ``` |
| 87 | +3. Cherry-pick the **merge commit** (not the individual commits): |
| 88 | + ```bash |
| 89 | + gh pr view <PR#> --json mergeCommit |
| 90 | + git cherry-pick <merge-commit-sha> |
| 91 | + ``` |
| 92 | +4. Push and create PR against the release branch: |
| 93 | + ```bash |
| 94 | + git push -u origin backport-<PR#>-to-<branch> |
| 95 | + gh pr create --base <branch> --head <user>:backport-<PR#>-to-<branch> |
| 96 | + ``` |
| 97 | + |
| 98 | +## AsciiDoc Conventions |
| 99 | + |
| 100 | +### File Naming |
| 101 | +- Lowercase with dashes: `installing-che-on-openshift.adoc` |
| 102 | +- Partials prefixed in includes: `include::partial$filename.adoc[]` |
| 103 | + |
| 104 | +### Page Structure |
| 105 | +```asciidoc |
| 106 | +[id="page-id"] |
| 107 | += Page Title |
| 108 | +:description: Brief description |
| 109 | +:keywords: comma, separated, keywords |
| 110 | +:navtitle: Navigation Title |
| 111 | +:_content-type: ASSEMBLY|CONCEPT|PROCEDURE|REFERENCE |
| 112 | +``` |
| 113 | + |
| 114 | +### Content Types |
| 115 | +- **ASSEMBLY** - Collection of modules describing a user story |
| 116 | +- **CONCEPT** - Explanation/description |
| 117 | +- **PROCEDURE** - Step-by-step how-to |
| 118 | +- **REFERENCE** - Reference material |
| 119 | + |
| 120 | +### Attributes |
| 121 | +Product-specific values are defined in `antora.yml` (200+ attributes). Use attributes instead of hardcoded values: |
| 122 | +- `{prod-short}` - Short product name |
| 123 | +- `{prod}` - Full product name |
| 124 | +- `{prod-ver}` - Product version (e.g., 7.115) |
| 125 | + |
| 126 | +## CI/CD Pipeline (GitHub Actions) |
| 127 | + |
| 128 | +On PRs: |
| 129 | +- **build-and-validate-on-pr** - Antora build + htmltest link validation |
| 130 | +- **vale** - Language linting (fails on errors) |
| 131 | +- **container-on-pull-request** - Verifies container builds |
| 132 | +- **publish-netlify** - Deploys preview site, posts comment with URL |
| 133 | + |
| 134 | +On merge to main: |
| 135 | +- **build-and-validate-on-push** - Full build + validation |
| 136 | +- **container-build** - Build and push container to Quay.io |
| 137 | +- **call-publication-builder** - Publishes to publication branch |
| 138 | + |
| 139 | +## Common Gotchas |
| 140 | + |
| 141 | +### AsciiDoc Callout Lists |
| 142 | +An IMPORTANT/NOTE/TIP block between callout items breaks numbering. The block must be integrated as a sub-paragraph of the preceding callout using the `+` continuation, not placed standalone between callout items. |
| 143 | + |
| 144 | +### Container Build Failures |
| 145 | +The `@antora/assembler` npm package must be pinned (e.g., `@1.0.0-beta.14`) in the Containerfile. Unpinned versions can cause exit code 1 during container builds. |
| 146 | + |
| 147 | +### External Link Failures |
| 148 | +Transient external link failures (e.g., cert-manager.io timeouts) are handled by `IgnoreExternalBrokenLinks: true` in `.htmltest.yml`. Persistently broken URLs should be added to the `IgnoreURLs` list. |
| 149 | + |
| 150 | +### Cherry-pick Conflicts |
| 151 | +When cherry-picking between branches, the `configuring-proxy.adoc` file has had formatting differences between branches. Always verify the cherry-pick applied cleanly. |
| 152 | + |
| 153 | +## PR Conventions |
| 154 | + |
| 155 | +### Title Prefixes |
| 156 | +- `docs:` - Documentation (no procedures), engineering review mandatory |
| 157 | +- `procedures:` - Includes procedures, testing mandatory |
| 158 | +- `chore:` - Routine, release, tooling, version upgrades |
| 159 | +- `fix:` - Fix build, language, links, or metadata |
0 commit comments