Open dboehmer opened 11 months ago
Thanks for sharing your experience! There are surely always opportunities for improvement.
Documentation for Rex 1.14.3 says on 1.4:
Furthermore, all features from earlier versions are activated.
In other words, feature flags that look like a version number configure everything that is configured by other, earlier feature flags that look like a version number. For example 1.4
includes all versioned feature flags below: 1.3
, 1.0
, 0.56
, 0.55
, 0.54
, 0.53
, 0.51
, 0.35
and 0.31
.
For reference, the feature flags are processed here. As a general rule they set configuration options provided by Rex::Config, or in some cases set/initialize some other internal variables, or maybe import otherwise optional modules.
Presenting that amount of information could quickly get overwhelming, so it would be nice to find a way to describe all that in a condensed way.
These are my initial questions hoping to catalyze ideas:
ps.: rex -d
also shows the list of toggled features at the beginning of the debug output for cross-checking what Rex thinks about its config.
I'd like kindly point to our support channels, for usually much faster turnaround times in case of questions. Especially GitHub discussions, our Matrix/IRC channels (these chats are bridged, so they are the same), or even my open source office hours.
For quick reference, we generally strive to:
@ferki, Now the documentation has made it completely unclear what flag 1.4 finally includes.
I propose to name the digital flags as a - Feature bundle. In the documentation, you first need to describe the block with bundles, as is done in the Perl documentation - https://perldoc.perl.org/feature#FEATURE-BUNDLES
For example:
1.4 autodie no_tty template_ng task_chaining_cmdline_args
1.3 autodie no_tty template_ng
1.0 autodie no_tty
0.56 autodie
[...]
Then a list of all named features without digital feature bundle. It might be useful to add "Enabled since v.v" with "Available since v.v" in this list
@ferki, Now the documentation has made it completely unclear what flag 1.4 finally includes.
While I have my reservations about being "completely unclear", I agree it's harder to read for humans than it could be.
I propose to name the digital flags as a - Feature bundle. [...] as is done in the Perl documentation - https://perldoc.perl.org/feature#FEATURE-BUNDLES
I like this idea a lot. This is largely the same concept as in Perl itself, and it makes sense stay close to lower the mental overhead.
Feature bundles map to sets of feature flags in general, though there are couple of exceptions when they set other configuration options too. This may need to be documented in a different format (or those cases may be converted into feature flags, if that makes more sense).
Then a list of all named features without digital feature bundle. It might be useful to add "Enabled since v.v" with "Available since v.v" in this list
As a note, Perl docs order concepts the other way around, and it may worth introducing the named flags before the feature bundles which groups them.
"Availability since" information is already documented for each feature flag, and could be reused in a reformatted version.
I'm not sure about the value of "enabled since" information. The main reason to add feature flags is to keep backwards compatibility, and as a general rule they don't get enabled by default. The single exception I'm aware of is the reporting
feature flag, and the commit history unfortunately doesn't make it clear whether it was intentional or not.
Overall, I support the idea of staying similar to Perl concepts with the documentation of Rex feature flags and bundles, and I'm willing to work together towards this on a PR. Hopefully the above quick details are good guidelines around the shape of the solution imagined here.
Given the potential scope and size of this topic, it may be better to convert this bug report into a discussion, and address the topic in a series of PRs and logical commits. I guess we'll be better able to judge that during implementation-time.
Describe the bug
In #1606 I learned I needed to use a more recent feature flag to get my desired behavior. So I went for
1.4
and had already trouble understand which other flags this would imply. I tried1.4
only and just learned through pain that this does not includeexec_autodie
. I revisited the documentation and think this is not my fault.Documentation for Rex 1.14.3 says on
1.4
:The list of flags is quite long and it also contains conflicting flags like
autodie
no_autodie
Expected behavior
Can you extend the documentation to include a list of what
1.4
and other meta flags actually mean?How to reproduce it
perldoc Rex
Code example
No response
Additional context
No response
Rex version
1.14.3
Perl version
5.38
Operating system running rex
Linux
Operating system managed by rex
Linux
How rex was installed?
cpan client