PE: wrong documentation about branch prefixes

[bastelfreak]

Describe the Bug

please have a look at https://www.puppet.com/docs/pe/2023.7/r10k_customize_config.html#r10k_configuring_sources-r10k-sources-prefix.

For example, the following settings might cause errors or confusion because there would be two main-modules environments deployed to the same base directory.

and this is the example config:

myorg: 
  remote: "git://git-server.site/myorg/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: true
  invalid_branches: 'error'
mysource: 
  remote: "git://git-server.site/mysource/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: true
  invalid_branches: 'correct_and_warn'

This is a bit confusing. There will never be an environment named main-modules. Because the config has prefix set to true for both control repos. So every branch will be prefix either myorg_ or mysource_ and there's never a conflict. And the example environment main-modules is identical to the git repository name, which also confuses.

However, by changing one prefix to "testing", the two environments become more distinct, since the directory would now have a myorg-main-modules environment and a testing-main-modules environment:

That's wrong. r10k uses the prefix, then _, then the branch name. - isn't an allowed character in branch names. If we assume that each repository contains a branch named main-modules the result would be just mysource_main_branch for the second repo and nothing will be deployed for the first repo because it has invalid_branches set to true. Since the - in main-branch isn't allowed, the branch won't be deployed at all.

Expected Behavior

A correct documentation

Steps to Reproduce

Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'

Environment

• Version [e.g. 1.27.0]
• Platform [e.g. Ubuntu 18.04]

Additional Context

• https://github.com/puppetlabs/r10k/blob/main/doc/dynamic-environments/configuration.mkd#prefix has correct information
• I debugged this because I wanted to know if r10k just prepends the prefix. It doesn't it prepends the prefix and then _

[github-actions]

Migrated issue to PUPDOC-5660