README - have meta-states and sub-state headings.

[noelmcloughlin]

I would recommend "Available States" section in README is split.

• Available Meta-States
• Available Sub-States

See example at https://github.com/saltstack-formulas/lvm-formula#available-meta-states

[baby-gnu]

I agree that we should provide a better way to distinguish between meta and sub states and separate components. Maybe using the order in which they are called?

For example:

Available Meta states

Setup

• template
• template.subcomponent

Clean

• template.subcomponent.clean
• template.clean

Available substates

Setup

• template.package
• template.config
• template.service
• template.subcomponent.config

Clean

• template.subcomponent.config.clean
• template.service.clean
• template.config.clean
• template.package.clean

[baby-gnu]

I think that if we have more than one configuration file, we should consider template.config as a meta-state and each individual file as sub-state, for example:

Available Meta states

• template.config

Available substates

• template.config.configfile1
• template.config.configfile2

[noelmcloughlin]

Substates are really useful for advanced users needing granularity, or building a solution needing to call one substate (i.e.setup a repository) without forcing entire formula on them.

Since many software has official API the sub-states can match API calls. See lvm-formula and devstack-formula.cli states for example - the API = SUB-STATES.

Related to this is https://github.com/saltstack-formulas/template-formula/pull/136 since there is duplication of states when the README is generated.

[myii]

Available Meta states

...

Available substates

@baby-gnu While reviewing the lvm-formula PR, I'd like to suggest a minor adjustment to these headings:

-Available Meta states
+Available meta-states

...

-Available substates
+Available sub-states

[baby-gnu]

@myii I completely agree, this was just a proposal for discussion.

Thanks.

[myii]

@baby-gnu You're welcome, thanks for the feedback.