Documentation lacks clear info which feature flags are activated by default

[dboehmer]

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 tried 1.4 only and just learned through pain that this does not include exec_autodie. I revisited the documentation and think this is not my fault.

Documentation for Rex 1.14.3 says on 1.4:

Furthermore, all features from earlier versions are activated.

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

[ferki]

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:

• What would you consider a cleaner way to present the information you felt missing?
• Would it be enough to clarify the feature flags that look like a version number in the scope of this issue, or are you expecting a larger overhaul?
• What would be a good short name to establish instead of feature flag that look like a version number?

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:

• encourage communication and collaboration on more interactive channels (as overwhelming majority of interactions are variations of "why does it...?" or "how do I...?")
• use GitHub issues as todo items for actions which are already decided as "this needs a change" through discussion (~"there is an agreement that something has to be changed, let's create an issue")
• use pull requests as change proposals to implement what a design decision on the issues (~"we settled on an an idea how we want to change it, check out this proposal")

[bes-internal]

@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]

@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.