Add new build target for foremanctl #4506
Conversation
Reviewer's guide (collapsed on small PRs)Reviewer's GuideIntroduces a new Flow diagram for Makefile html target with new foremanctl contextflowchart TD
A[html target] --> B[build-foreman-el]
A --> C[build-foreman-deb]
A --> D[build-foremanctl]
A --> E[build-katello]
subgraph pattern_build
direction LR
B --> F[make -C guides html BUILD=foreman-el]
C --> G[make -C guides html BUILD=foreman-deb]
D --> H[make -C guides html BUILD=foremanctl]
E --> I[make -C guides html BUILD=katello]
end
F --> J[foreman-el HTML guides]
G --> K[foreman-deb HTML guides]
H --> L[foremanctl HTML guides]
I --> M[katello HTML guides]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
github-actions
bot
added
Needs tech review
aneta-petrova
removed
Needs tech review
| } | ||
| }, | ||
| { | ||
| "title": "Containerized Foreman", |
There was a problem hiding this comment.
This is almost certainly not a good name for the new build target and I'm open to suggestions.
| ifdef::foremanctl[] | ||
| :FeatureName: The `foremanctl` deployment utility | ||
| include::common/modules/snip_technology-preview.adoc[] | ||
| endif::[] |
There was a problem hiding this comment.
I wonder if we should add this to every foremanctl guide we add to navigation, until the tool becomes more stable.
aneta-petrova
force-pushed
the
foremanctl-flavor
branch
from
7a6533b to
78778e9
Compare
|
Hi @ekohl and @jafiala, this is the result of what we discussed earlier today -- a new build target for foremanctl docs:
As @maximiliankolb correctly pointed out in #3975 (comment), any line that's currently included with other conditionals (such as Please let me know what you think. The point of this PR is to investigate whether this approach will scale in the future (compared to the other alternatives described in this PR's description) so feedback is welcome. |
Includes switching Quickstart from tabs to a separate foremanctl guide
aneta-petrova
force-pushed
the
foremanctl-flavor
branch
from
78778e9 to
6386d76
Compare
ekohl
left a comment
ekohl
left a comment
There was a problem hiding this comment.
This indeed looks very much like what we discussed and makes it easy for others to see what we're talking about. I'm positively surprised how small the whole diff really is.
| :foreman: | ||
| endif::[] | ||
| ifeval::["{build}" == "foremanctl"] | ||
| :foremanctl: |
There was a problem hiding this comment.
Now that I see this I'm wondering: initially we discussed a more feature flag idea. My idea was that we can modify the satellite flavor to also define foremanctl. Seeing this here makes me worried we'll break stuff. On the other hand, perhaps that's unfounded.
Testing that idea might require some real content to be in place.
There was a problem hiding this comment.
Can you please elaborate on how you think the satellite flavour could be made to also define foremanctl?
There was a problem hiding this comment.
We can add :foremanctl: to attributes-satellite.adoc to "flip" the feature on but that can have unintended consequences. That's what I had in my head as a theory and I'd love to come up with a way to test that theory though I doubt we can without filling up the foremanctl guide first.
There was a problem hiding this comment.
Wouldn't that effectively make foremanctl docs development downstream first?
As an alternative, in #4507 I'm looking into creating a new foremanctl target for each existing build target to get the ability to use a feature flag. It doesn't build but shows yet another alternative approach.
There was a problem hiding this comment.
Wouldn't that effectively make foremanctl docs development downstream first?
Maybe I wasn't clear. I was saying that we start building out the foremanctl flavor (build). Once downstream is ready, we "flip the switch" and also add the foremanctl attribute to the satellite flavor. And now I'm asking (out loud) if that is feasible. That doesn't mean the foremanctl flavor goes away in upstream because that's still a valid target. It just means that the satellite flavor will then be closer to the foremanctl flavor than the katello flavor.
There was a problem hiding this comment.
I suspect previewing the changes might be trickier with what you're suggesting. Also extending the single foremanctl build target from being satellite-compliant to being fit for any other build target.
In the meantime #4507 started building correctly. That approach shows a separate preview for each build target + flavor combination:
- Foreman EL
- Foreman Deb
- Foreman + Katello
- orcharhino
- Satellite
- Foreman EL and foremanctl
- Foreman Deb and foremanctl
- Foreman + Katello and foremanctl
- orcharhino and foremanctl
- Satellite and foremanctl
Then, once any existing build target goes into full foremanctl mode, we could just drop the pre-foremanctl build and replace it with the corresponding foremanctl build. So in a way, the same thing we intended to do when we created a separate foremanctl server installation guide (in #3975), with the intention of eventually replacing the pre-foremanctl guide with it (in #4087).
2 participants
What changes are you introducing?
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
Up until now, foremanctl documentation has been developed with the expectation that with a future version, Foreman will switch from using the current Puppet-based installer to the new containerized deployment tool named foremanctl. This is why in a previous PR #3975, a new guide directory was created, with the expectation that it would at a certain point replace the existing guide.
Now it's become clear that the switch to foremanctl will be more gradual upstream and for some time, foremanctl will exists alongside non-foremanctl builds. This PR investigates an alternative approach where a new build target is created.
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
Alternative approaches that have been considered:
Contributor checklists
Please cherry-pick my commits into:
Summary by Sourcery
Introduce a separate foremanctl documentation build target and integrate it into builds, navigation, and guides.
New Features:
Enhancements: