Move information re: allowed characters for FQBN component to specifications

[per1234]

Please check if the PR fulfills these requirements

See how to contribute

• The PR has no duplicates (please search among the Pull Requests
  before creating one)
• The PR follows
  our contributing guidelines
• [N/A] Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)
• [N/A] UPGRADING.md has been updated with a migration guide (for breaking changes)
• [N/A] configuration.schema.json updated if new parameters are added.

What kind of change does this PR introduce?

Docs update

What is the current behavior?

Arduino CLI restricts which characters are supported for use by platform developers in their vendor, architecture, board, custom board menu, and custom board option identifiers:

arduino-cli/pkg/fqbn/fqbn.go

Lines 45 to 93 in faf79a7

	var fqbnValidationRegex = regexp.MustCompile(`^[a-zA-Z0-9_.-]*$`)
	var valueValidationRegex = regexp.MustCompile(`^[a-zA-Z0-9=_.-]*$`)
	// Parse parses an FQBN string from the input string
	func Parse(fqbnIn string) (*FQBN, error) {
	// Split fqbn parts
	fqbnParts := strings.Split(fqbnIn, ":")
	if len(fqbnParts) < 3 || len(fqbnParts) > 4 {
	return nil, errors.New(i18n.Tr("not an FQBN: %s", fqbnIn))
	}
	fqbn := &FQBN{
	Vendor: fqbnParts[0],
	Architecture: fqbnParts[1],
	BoardID: fqbnParts[2],
	Configs: properties.NewMap(),
	}
	if fqbn.BoardID == "" {
	return nil, errors.New(i18n.Tr("empty board identifier"))
	}
	// Check if the fqbn contains invalid characters
	for i := 0; i < 3; i++ {
	if !fqbnValidationRegex.MatchString(fqbnParts[i]) {
	return nil, errors.New(i18n.Tr("fqbn's field %s contains an invalid character", fqbnParts[i]))
	}
	}
	if len(fqbnParts) > 3 {
	for _, pair := range strings.Split(fqbnParts[3], ",") {
	parts := strings.SplitN(pair, "=", 2)
	if len(parts) != 2 {
	return nil, errors.New(i18n.Tr("invalid config option: %s", pair))
	}
	k := strings.TrimSpace(parts[0])
	v := strings.TrimSpace(parts[1])
	if k == "" {
	return nil, errors.New(i18n.Tr("invalid config option: %s", pair))
	}
	if !fqbnValidationRegex.MatchString(k) {
	return nil, errors.New(i18n.Tr("config key %s contains an invalid character", k))
	}
	// The config value can also contain the = symbol
	if !valueValidationRegex.MatchString(v) {
	return nil, errors.New(i18n.Tr("config value %s contains an invalid character", v))
	}
	fqbn.Configs.Set(k, v)
	}
	}
	return fqbn, nil
	}

This information is only documented(?) in the "FAQ" (#2509). A platform developer is unlikely to ever think to look for such information in the FAQ.

In addition, the inclusion of such information in the FAQ is not appropriate as this is intended for end users of the Arduino CLI application and end users have no control over which characters were used by the platform developers in their identifiers. So the presence of the information in the FAQ only harms readability by introducing unnecessary complexity into a subject that users often struggle to understand (e.g., arduino/arduino-cli#355).

It is especially problematic that this information is not properly documented because the restrictions were introduced relatively recently and there are established platforms which do not comply, and which work perfectly with Arduino IDE 1.x, which leads the affected developers and users to the conclusion that the resulting problems are caused by a bug in the Arduino development tools, rather than an intentional decision by the Arduino developers to refrain from supporting the previously functional identifiers (e.g., #2901).

What is the new behavior?

The requirement is formally documented in the appropriate locations in the Arduino Package Index Specification and Arduino Platform Specifications.

This will ensure that developers will have access to this important information which will allow them to produce compliant platforms.

This will ensure that those investigating problems with non-compliant platforms will be able to find the information in the expected location.

Does this PR introduce a breaking change, and is titled accordingly?

No breaking change.

Other information