Format requirements should be mentioned in the docs

Users should know about the restrictions in the first place, not from this error message:

Issues while validating snapcraft.yaml: The 'name' property does not match the required schema: 'WoeUSB' is not a valid snap name. Snap names consist of lower-case alphanumeric characters and hyphens. They cannot be all numbers. They also cannot start or end with a hyphen.

Corresponding section:


We can totally add the specifications of each field but I think this is a great response to a possible mistake and potentially enough. Often software is not very clear to “what the hell happened” and this clearly says you wrote the name input wrong and tells you how it should be like. My point is, despite you are not told in the documentation the name field (or any other) has some format requirements, when you write something wrong, it immediately tells you clearly what, why and how to fix it.

1 Like

You can’t have a blank specification then call a syntax error a “mistake”. The error message is good, but doesn’t help me to choose a name a priori.

1 Like

…or you should directly mention it in the spec to let the users try-and-error

Well, my point was more that it is okay if users do not have this information despite being possible (and relatively easy) to add this information to the documentation. We might have different perspectives on this though :slight_smile:

Heh. The annoying thing is you have to name your app after the snap if you don’t want to end up with an ugly snapname.appname invocation. So trial and error involves renaming files as well as fiddling with the field in snacraft.yaml. Better to have it named properly int he first place.

The name of the app and the snap are completely independent of the name of any files inside the snap. The only thing you need to change to rename the application is the entry in snapcraft.yaml itself (actually, snap.yaml, but that’s a side effect of changing snapcraft.yaml when building snaps with it).

Also, you’re right that we need better documentation in general, but @gsilvapt has a good point that the most critical place to report properly is when using the software itself. It detected what was wrong, and said exactly what to fix. Most people won’t even reach that docs when that happens.

But again, we’re indeed working on docs. So we’re all in agreement pretty much.

1 Like