Skip to content

Commit 0951124

Browse files
yaacovyaacov
authored
Merge pull request #866 from yaacov/update-upstream-ci
chore(ci): migrate upstream site to just-the-docs theme
2 parents 7480b04 + 33f61a8 commit 0951124

38 files changed

+724
-1902
lines changed

‎.cursor/skills/git-commit/SKILL.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
name: git-commit
3+
description: Generate git commit messages following MTV project conventions. Use when the user asks to commit, create a commit, write a commit message, or stage and commit changes.
4+
---
5+
6+
# Git Commit Message Skill
7+
8+
## Workflow
9+
10+
1. Run `git diff --staged` (and `git status`) to understand the changes.
11+
2. Determine whether an MTV Jira issue applies. Ask the user for the MTV issue number if not already known.
12+
3. **Always ask the user**: "Was AI used as a co-author for these changes?" If yes, append the AI co-author trailer.
13+
4. Compose the commit message using the appropriate template below.
14+
5. Commit using a HEREDOC so the multi-line message is preserved.
15+
16+
## Template A — With MTV Issue
17+
18+
Use when an MTV-xxx Jira issue is associated with the change.
19+
20+
```
21+
MTV-xxx | short description of the change
22+
23+
Explain why this change is needed. Focus on intent, not mechanics.
24+
25+
Resolves: MTV-xxx
26+
Ref: https://issues.redhat.com/browse/MTV-xxx
27+
28+
Co-authored-by: AI Assistant <ai-assistant@noreply.redhat.com>
29+
30+
Signed-off-by: {name} <{email}>
31+
```
32+
33+
- The title line is: `MTV-xxx | short description` (imperative mood, lowercase after the pipe).
34+
- The body paragraph explains **why**, not what.
35+
- `Resolves` and `Ref` reference the same MTV issue.
36+
- Omit the `Co-authored-by` line if AI was **not** a co-author.
37+
38+
## Template B — Without MTV Issue
39+
40+
Use for housekeeping work that has no Jira ticket (docs cleanup, CI tweaks, dependency bumps, etc.).
41+
42+
```
43+
chore(type): short description of the change
44+
45+
Explain why this change is needed.
46+
47+
Resolves: none
48+
49+
Co-authored-by: AI Assistant <ai-assistant@noreply.redhat.com>
50+
51+
Signed-off-by: {name} <{email}>
52+
```
53+
54+
- The title follows conventional-commit style: `chore(type): description`.
55+
Common types: `docs`, `ci`, `deps`, `lint`, `test`, `config`.
56+
- `Resolves: none` — no Jira reference.
57+
- `Ref` line is **omitted entirely**.
58+
- Omit the `Co-authored-by` line if AI was **not** a co-author.
59+
60+
## Commit Command
61+
62+
Always use a HEREDOC to preserve formatting:
63+
64+
```bash
65+
git commit -m "$(cat <<'EOF'
66+
MTV-123 | add migration network performance guidance
67+
68+
Document the impact of dedicated migration networks on transfer
69+
throughput so users can make informed network topology decisions.
70+
71+
Resolves: MTV-123
72+
Ref: https://issues.redhat.com/browse/MTV-123
73+
74+
Signed-off-by: yaacov <kobi.zamir@gmail.com>
75+
Co-authored-by: AI Assistant <ai-assistant@noreply.redhat.com>
76+
EOF
77+
)"
78+
```
79+
80+
## Rules
81+
82+
- Get the signer identity from `git config user.name` / `git config user.email`.
83+
- Never fabricate an MTV issue number — ask the user.
84+
- Always ask whether AI co-authored before composing the message.
85+
- Keep the title line under 72 characters.
86+
- Use imperative mood in the title ("add", "fix", "update", not "added", "fixes").

‎.cursor/skills/upstream-downstream/SKILL.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
name: upstream-downstream
3+
description: Guide for using upstream and downstream variables and conditional content in AsciiDoc modules. Use when writing, editing, or reviewing .adoc files, when using product names, CLI commands, namespaces, or operator names in documentation, or when adding build-specific content for upstream (Forklift) vs downstream (MTV).
4+
---
5+
6+
# Upstream & Downstream Authoring
7+
8+
## Golden Rule
9+
10+
Never hardcode a product name, CLI tool, namespace, or operator name. Always use the corresponding variable.
11+
12+
## Variable Definitions
13+
14+
Downstream values live in `documentation/modules/common-attributes.adoc`.
15+
Upstream overrides live in `_config.yml` under `asciidoctor.attributes`.
16+
17+
Upstream builds load `common-attributes.adoc` first, then `_config.yml` overrides. Any variable **not** overridden in `_config.yml` leaks the downstream value into upstream.
18+
19+
## Variable Quick Reference
20+
21+
| Variable | Upstream (Forklift) | Downstream (MTV) |
22+
|---|---|---|
23+
| `{build}` | upstream | downstream |
24+
| `{project-full}` | Forklift | Migration Toolkit for Virtualization |
25+
| `{project-short}` | Forklift | MTV |
26+
| `{project-first}` | Forklift | Migration Toolkit for Virtualization (MTV) |
27+
| `{virt}` | KubeVirt | OpenShift Virtualization |
28+
| `{a-virt}` | a KubeVirt | an OpenShift Virtualization |
29+
| `{ocp}` | OKD | Red Hat OpenShift |
30+
| `{ocp-short}` | OKD | OpenShift |
31+
| `{oc}` | kubectl | oc |
32+
| `{namespace}` | konveyor-forklift | openshift-mtv |
33+
| `{operator}` | forklift-operator | mtv-operator |
34+
| `{operator-name}` | Forklift Operator | MTV Operator |
35+
| `{rhv-full}` | oVirt | Red Hat Virtualization |
36+
| `{rhv-short}` | oVirt | RHV |
37+
| `{a-rhv}` | an oVirt | a Red Hat Virtualization |
38+
| `{manager}` | Engine | Manager |
39+
| `{must-gather}` | quay.io/kubev2v/forklift-must-gather:latest | registry.redhat.io/.../mtv-must-gather-rhel8:{project-z-version} |
40+
| `{vmw}` | *(not overridden)* | VMware |
41+
42+
### Downstream-only variables (no upstream override)
43+
44+
These exist only in `common-attributes.adoc` and are safe to use inside `ifeval::["{build}" == "downstream"]` blocks:
45+
46+
- `{operator-name-ui}` — Migration Toolkit for Virtualization Operator
47+
- `{ocp-name}` — OpenShift
48+
- `{ocp-version}` — e.g. 4.21
49+
- `{ocp-doc}` — link prefix to Red Hat OCP docs
50+
- `{project-version}` — e.g. 2.11
51+
- `{project-z-version}` — e.g. 2.11.0
52+
- `{mtv-plan}`, `{mtv-mig}` — Red Hat doc URLs
53+
54+
## Conditional Content
55+
56+
### Build-based conditionals (`ifeval`)
57+
58+
Use `ifeval` to show content only in one build:
59+
60+
```asciidoc
61+
ifeval::["{build}" == "upstream"]
62+
This sentence appears only in the Forklift (upstream) docs.
63+
endif::[]
64+
65+
ifeval::["{build}" == "downstream"]
66+
This sentence appears only in the MTV (downstream) docs.
67+
endif::[]
68+
```
69+
70+
**Critical syntax note:** The variable must be wrapped in curly braces — `"{build}"`, not `"build"`. Without braces the condition compares a literal string and silently never matches.
71+
72+
### Provider-specific conditionals (`ifdef`)
73+
74+
Modules reused across providers use `ifdef` guards. The attribute is set by the parent assembly via `:context:`.
75+
76+
Provider attributes: `vmware`, `rhv`, `ova`, `ostack`, `cnv`
77+
78+
```asciidoc
79+
ifdef::vmware[]
80+
= Adding a {vmw} vSphere source provider
81+
endif::[]
82+
ifdef::rhv[]
83+
= Adding {a-rhv} source provider
84+
endif::[]
85+
```
86+
87+
### UI vs CLI conditionals
88+
89+
```asciidoc
90+
ifdef::web[]
91+
. In the {ocp-short} web console, navigate to *Migration* > *Plans*.
92+
endif::[]
93+
ifdef::cli[]
94+
. Run `{oc} get plans -n {namespace}`.
95+
endif::[]
96+
```
97+
98+
### Context management in assemblies
99+
100+
Assemblies must save and restore `:context:` so nested includes don't clobber each other:
101+
102+
```asciidoc
103+
ifdef::context[:parent-context: {context}]
104+
:context: vmware
105+
106+
\include::modules/adding-source-provider.adoc[leveloffset=+1]
107+
108+
ifdef::parent-context[:context: {parent-context}]
109+
ifndef::parent-context[:!context:]
110+
```
111+
112+
## Variables in Code Blocks
113+
114+
Variables are **not** expanded inside literal blocks by default. Add the `subs` attribute:
115+
116+
```asciidoc
117+
[source,terminal,subs="attributes+"]
118+
----
119+
$ {oc} get pods -n {namespace}
120+
----
121+
```
122+
123+
For combined substitutions:
124+
125+
```asciidoc
126+
[options="nowrap" subs="+quotes,+attributes"]
127+
----
128+
$ {oc} get migration -n {namespace}
129+
----
130+
```
131+
132+
## Common Pitfalls
133+
134+
1. **"Red Hat {virt}"** — renders as "Red Hat KubeVirt" upstream. Wrap in a build conditional or use a dedicated variable.
135+
2. **Downstream-only variables in shared content** — if a variable has no upstream override (e.g. `{vmw}`), using it outside a downstream guard produces unexpected output upstream.
136+
3. **Forgetting `subs="attributes+"`** — variables appear as literal `{oc}` in code blocks without it.
137+
4. **Missing braces in `ifeval`** — `ifeval::["build" == "upstream"]` is always false; correct form is `ifeval::["{build}" == "upstream"]`.
138+
5. **Hardcoded "oc" or "kubectl"** — always use `{oc}` so the right CLI tool renders per build.
139+
6. **Hardcoded namespace** — always use `{namespace}` instead of writing `openshift-mtv` or `konveyor-forklift`.
140+
141+
## Module ID Convention
142+
143+
Module IDs must include the `{context}` suffix so the same module can be included in multiple contexts without ID collision:
144+
145+
```asciidoc
146+
[id="adding-source-provider_{context}"]
147+
= Adding a source provider
148+
```

‎.github/workflows/pages.yaml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,6 @@ jobs:
3939
run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
4040
env:
4141
JEKYLL_ENV: production
42-
continue-on-error: true
4342
- name: Upload artifact
4443
uses: actions/upload-pages-artifact@v3
4544

‎.jekyll-cache/Jekyll/Cache/Jekyll--Cache/b7/9606fb3afea5bd1609ed40b622142f1c98125abcfe89a76a661b0e8e343910‎

2.71 KB
Binary file not shown.

‎Gemfile‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,17 @@
11
# frozen_string_literal: true
2-
# Encoding.default_external = Encoding::UTF_8
3-
# Encoding.default_internal = Encoding::UTF_8
42

53
source "https://rubygems.org"
64

7-
# gem "asciidoctor-pdf"
8-
gem "asciidoctor"
9-
# gem "bundle"
10-
# gem "html-proofer"
11-
# gem "jekyll-theme-minimal"
12-
# gem "jekyll-feed"
13-
gem "jekyll-paginate"
14-
# gem "jekyll-redirect-from"
15-
# gem "jekyll-sitemap"
16-
# gem "jekyll-tagging"
17-
# gem 'jekyll-seo-tag'
18-
# gem "jekyll", ">= 3.5"
19-
# gem "premonition", ">= 4.0.0"
20-
# gem "pygments.rb"
21-
# gem "rake"
22-
#
23-
#
24-
gem "github-pages", group: :jekyll_plugins
5+
gem "jekyll", "~> 4.3"
6+
gem "just-the-docs", "~> 0.10"
257

26-
# ensures that jekyll-asciidoc is loaded first
278
group :jekyll_plugins do
28-
gem 'jekyll-asciidoc'
9+
gem "jekyll-asciidoc"
10+
gem "jekyll-seo-tag"
11+
gem "jekyll-sitemap"
12+
gem "jekyll-redirect-from"
13+
gem "jekyll-feed"
14+
gem "jekyll-include-cache"
2915
end
3016

31-
gemspec
17+
gem "asciidoctor"

0 commit comments

Comments
 (0)