Docs: A single source of truth for process/policies/expectations/requirements

canonical / snapcraft

Package, distribute, and update any app for Linux and IoT.

https://snapcraft.io

GNU General Public License v3.0

1.18k stars 442 forks source link

Docs: A single source of truth for process/policies/expectations/requirements #5042

Open sed-i opened 1 week ago

sed-i commented 1 week ago

What needs to get done

We should have a single source of truth for process/policies/expectations/requirements. Should include:

Ideally snaps should be organic to the app. Try to first reach out to the upstream developers to have this snap published officially.
If the snap is external to the repo and you're not the developer of the snapped app, namespace the snap like so: -
At least 4 characters
For Canonical employees, the snap should either be under a Canonical repository, or published through a personal store account.
If you require a classically confined snap, it will likely be approved if it fits one of the following categories:
- terminal emulators, multiplexers, and shells
- etc.

Why it needs to get done

Currently the information is segmented across systems and individuals, creating surprises in the snap registration process.

dilyn-corner commented 1 week ago

Snap provenance and names is covered here already, specifically...

Do not prefix or suffix the name, for instance with your username or “-snap.”

Ultimately, each name should be owned and published by members of the relevant project... However, if you are not associated with the project but want to help them create a snap, we welcome you to join snapcrafters, create the snap yourself, register the name and hand off to upstream projects when asked.

Caveat, of course:

There is a single exception for having your username as a suffix in a snap name: an unofficial snap that has no chance of being handed over to the official project. This should be done with extreme caution...

There's also a documented process for classically confined snaps here.

sed-i commented 1 week ago

Thanks @dilyn-corner!

The snapcraft CLI seems to encourage prefixing:

It would be nice if snapcraft cli and the webui point to the same reference. Currently, each has slightly different (and partial) messaging. More broadly, needing to contact team members for links to docs is suboptimal. We need to do something about discoverability.

dilyn-corner commented 1 week ago

Ha. That's Very Funny:tm:.

Agreed on the discoverability side; Graham Morrison and I have been working on these problems for quite some time.

Perhaps @medubelko has some idea of a plan surrounding these documents?

medubelko commented 1 week ago

@dilyn-corner @sed-i I agree that the discoverability isn't good and we should consolidate or remove the redundancies here.

@degville Do you know whether these pages were de-indexed deliberately?

degville commented 1 week ago

@medubelko They're not de-indexed deliberately. Definitely feel free to consolidate and remove redundancies as you see fit!

The reason why many pages are not in the navigation structure is that our Discourse tooling only allowed for 2 levels of menu depth, which made it infeasible to add all 600+ pages. This is why so many pages exist outside of the navigation. We now have 3 levels, but this still isn't enough, and we're hoping to enable 4.