Clarify generic packages use case, especially related to duplicate file names
Problem to solve
The documentation of generic packages can be improved on several points. These relate to the fact that by default a package version may have different files with the same file name, as seen below.
-
The setting to not allow duplicate packages: I first understood this as allowing duplicate package names. What is actually intended is duplicate file names within a particular package version. My misunderstanding was also in part caused by the fact that I would expect a setting for duplicate file names to be a project-level setting, and this is a group-level setting (#337810 suggests adding a project-level setting).
-
The API endpoint for downloading suggests that files are uniquely identified by file names, which is not the case. It is not clear from the docs which file you get when there are multiple matches. (According to release-cli!108 (comment 643627672), the latest is returned.)
I'm writing this up per request by @trizzi from #277092 (comment 751596116).
Further details
To be honest I'm completely unsure what use case you have in mind for the generic packages. Here is what I imagine:
- I have a project camilstaps/my_app. Let's say it's an application that can be distributed as a binary.
- I build the binary for various platforms in CI.
- If the CI job is for a tag v1.2.3, I upload a binary to
/projects/${CI_PROJECT_ID}/packages/generic/my_app/1.2.3/my_app_linux_x64
. - (Optionally, each generic package version may also have files like CHANGELOG.md, LICENSE, etc.)
- If I upload the same file for the same version, I expect an error, because packages, like tags, would normally be immutable (this is my experience with tools like npm).
To me this seems like the most rudimentary way to use any package registry. This is also what is suggested by the idea to use generic packages for release assets. There are two ways in which GitLab generic packages differ:
- Uploading the same binary for the same version again does not give an error. Instead, a second file with the same name is created. It is not clear what the use case for this is (cf. release-cli!108 (comment 644060275) that the UI is confusing).
- GitLab has package names, which I wouldn't need because I'm only releasing
my_app
in the projectmy_app
. But I can imagine this is useful if you're building different packages from the same source, e.g. library headers and a static library.
I would expect that these (especially the first) are clearly explained in the documentation.
Proposal
- Start from scratch with writing an introduction to generic packages. It is clear what I can do with an npm registry or with the docker container registry, because it's basically another endpoint for a service that you will typically already be familiar with. Generic packages are some sort of cloud storage, but it is unclear how you imagine that people should use it. Write up what the basic use case is and document how that can be achieved. (The documentation currently refers to a sample project, but that does not really show a use case, it is more focused on incrementing the CI variable.)
- I would guess that I'm not the only one who expects generic packages to be what I expected them to be, so I would clearly indicate where your use case deviates from what I described above.
- In particular, I think it should be highlighted that the default behaviour is that duplicate file names are allowed. I doubt this is intuitive in any workflow.
- Make it clear what the "do not allow duplicates" setting does. Since this is a group-level setting, I first assumed it prevented duplicate package names in the same group, while it actually prevents duplicate file names within a particular package version. The documentation seems to allow for either reading (though I would say mine is preferred). In particular the documentation now says that you can give a regex for exceptions of "names and/or versions of packages to allow", which should probably be file names that can be duplicated rather than package names / versions?
- Clarify the behaviour of the API download endpoint: which file is returned in case of duplicates? Is there a way to get another version of the same file?
- In general, make sure that the documentation is everywhere very clear whether a project, package, version, or file is meant.
Who can address the issue
Documentation writers. Possibly a product owner needs to confirm what the intended behaviour is.