identifiers rev 1.1: allow underscore

concourse/concourse#6070

Signed-off-by: Alex Suraci <[email protected]>

Author: vito

040-valid-identifiers/proposal.md

@@ -1,3 +1,4 @@
+* Revision: [1.1](#revision-1.1)
 * RFC PR: [concourse/rfcs#40](https://github.com/concourse/rfcs/pull/40)
 * Concourse Issue: [concourse/concourse#5810](https://github.com/concourse/concourse/issues/5810)
 
@@ -28,22 +29,24 @@ CLI uses `PIPELINE/JOB` notation for flags specifying a job, but this would be
 ambiguous if your pipeline or job names allowed `/` in their name. For example,
 `foo/bar/baz` could either be (`foo/bar`, `baz`) or (`foo`, `bar/baz`).
 
-Allowing whitespace, capitalization, and mixed use of `_` and `-` also results
-in inconsistent naming conventions between Concourse users. A 'deploy to prod'
-job may be called any of the following:
+Allowing whitespace and capitalization along with `_` and `-` results in
+inconsistent naming conventions between Concourse users. A 'deploy to prod' job
+may be called any of the following:
 
+* `prod-deploy`
 * `deploy to prod`
 * `deploy-to-prod`
 * `deploy_to_prod`
 * `Deploy to prod`
+* `deploy to Prod`
 * `Deploy to Prod`
 
-This variance is largely cosmetic and makes it difficult for a new Concourse
-user on an existing team to predict the name of a given job.
-
 Permitting so many different naming conventions makes the Concourse UX, which
 is largely text-based, feel inconsistent between different projects with
-different naming conventions.
+different naming conventions. This inconsistency may seem insignficant to users
+who only use Concourse within a single team, but it will become more pronounced
+if/when the Concourse project introduces a central place to share re-usable
+pipeline templates and other configuration.
 
 Allowing spaces also makes it awkward to pass identifiers to the `fly` CLI, as
 they would have to be explicitly quoted so they're not parsed as separate
@@ -60,17 +63,18 @@ reduce the allowed character set for Concourse identifiers.
 
 The following characters will be permitted:
 
-* Unicode letters.
+* Non-uppercase Unicode letters (i.e. lowercase or letter with no uppercase).
 * Decimal numbers.
-* Hyphens (`-`), as the canonical word separator.
+* Hyphens (`-`) and underscores (`_`), as the canonical word separators.
 * Periods (`.`), in order to support domain names and version numbers.
 
-All letters will be converted to lowercase. This is to enforce
-case-insensitivity and to present a consistent UI/UX while still supporting
-languages that don't have any casing (e.g. Japanese).
-
-Notably, the underscore character (`_`) is forbidden. This is to further
-enforce consistency in word separators.
+It's worth noting that both hyphens (`-`) and underscores (`_`) are allowed as
+word separators. While this may lead to the kind of fragmentation this proposal
+aims to prevent, allowing both is more pragmatic than forbidding either: `-` is
+already commonplace, while `_` is more consistent with config params like
+`resource_types` and is commonly used with other tools and naming conventions
+(e.g. `x86_64`). The first iteration of this proposal did not allow the use of
+underscore; see [Revision 1.1](#revision-1.1) for details.
 
 All identifiers must start with a valid letter. Allowing digits or symbols at
 the beginning would allow for a few confusing situations:
@@ -86,30 +90,22 @@ With Go's [`re2`](https://github.com/google/re2/wiki/Syntax) syntax, a valid
 identifier would be matched by the following regular expression:
 
 ```re
-^\p{L}[\p{L}\d\-.]*$
+^[\p{Ll}\p{Lt}\p{Lm}\p{Lo}][\p{Ll}\p{Lt}\p{Lm}\p{Lo}\d\-.]*$
 ```
 
-This scheme is very similar to the [restrictions on valid
-hostnames][valid-hostnames], with the exception that any Unicode letter is
-allowed instead of `a-z`. This similarity is incidental, but it's a convenient
-comparison to draw as hostnames and Concourse identifiers have similar needs:
-to be used in URLs, to be referenced from the commandline (`fly`), to be
-referenced in configuration (pipelines), and to be case-insensitive.
-
 ## Renaming existing data
 
-The following API resources can already be renamed manually:
+All API resources can already be renamed manually:
 
 * Pipelines can be renamed with `fly rename-pipeline`.
 * Teams can be renamed with `fly rename-team`.
 * Jobs can be renamed by updating their `name` and specifying the old name as
-  [`old_name:`](https://concourse-ci.org/jobs.html#job-old-name). This will
-  preserve their build history.
+  [`old_name`][jobs-old-name]. This will preserve the job's build history.
+* Resources can be renamed in the same fashion by setting
+  [`old_name`][resources-old-name]. This will preserve the resource's state
+  (i.e. disabled versions, pinning).
 * Step names can be renamed without any migration necessary.
 
-Resources cannot currently be renamed; support for doing so will need to be
-implemented before enforcing resource identifier validation.
-
 ## Easing the transition
 
 Enforcing rules about identifiers is easy. Doing this in a way that doesn't
@@ -121,7 +117,9 @@ interact with mission-critical pipelines that have now-invalid identifiers
 would be a major problem. Users should not be punished for upgrading.
 
 To ease this pain, we can allow existing data to stay as-is, and only enforce
-the identifier rules for newly created teams and pipelines.
+the identifier rules for newly created teams and pipelines. Additionally,
+these validations can be implemented as warnings for a long period of time so
+that users have time to adapt.
 
 Existing data will still be fully functional and writable (i.e. updated with
 `fly set-pipeline`, `fly set-team`), and Concourse can emit warnings for any
@@ -172,5 +170,17 @@ n/a
 
 * n/a
 
+
+# Revisions
+
+## Revision 1.1
+
+In response to feedback in [concourse/concourse#6070][underscores-issue] this
+RFC has been amended to allow the use of the underscore character (`_`) in
+identifiers.
+
+
 [var-sources-rfc]: https://github.com/concourse/rfcs/pull/39
-[valid-hostnames]: https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames
+[underscores-issue]: https://github.com/concourse/concourse/issues/6070
+[jobs-old-name]: https://concourse-ci.org/jobs.html#schema.job.old_name
+[resources-old-name]: https://concourse-ci.org/resources.html#schema.resource.old_name