<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=297471) </details> <!--IssueSummary end--> <!-- * Use this issue template for suggesting new docs or updates to existing docs. Note: Doc work as part of feature development is covered in the Feature Request template. * For issues related to features of the docs.gitlab.com site, see https://gitlab.com/gitlab-org/gitlab-docs/issues/ * For information about documentation content and process, see https://docs.gitlab.com/ee/development/documentation/ --> ### Problem to solve <!-- Include the following detail as necessary: * What product or feature(s) affected? * What docs or doc section affected? Include links or paths. * Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs? * Any other ideas or requests? --> The directory structure format used in the generated project repository archives [retrieved by the API](https://docs.gitlab.com/ee/api/repositories.html#get-file-archive) is not documented as a stable behavior in the API docs. ### Further details <!-- * Any concepts, procedures, reference info we could add to make it easier to successfully use GitLab? * Include use cases, benefits, and/or goals for this work. * If adding content: What audience is it intended for? (What roles and scenarios?) For ideas, see personas at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/ or the persona labels at https://gitlab.com/groups/gitlab-org/-/labels?utf8=%E2%9C%93&subscribed=&search=persona%3A --> The [Repository API](https://docs.gitlab.com/ee/api/repositories.html#get-file-archive) provides a way to retrieve archives of any project: ``` GET /projects/:id/repository/archive[.format] ``` These can be downloaded in multiple formats (TAR.GZ, ZIP) and carry contents of a `git-archive` command run over the repository under a specific prefix structure. For ex. requesting a branch name nests the content within a directory prefix named `project-branch-fullsha/`. (Test with:) ``` curl -o foo.zip https://gitlab.com/api/v4/projects/gitlab-org%2Fgitlab/repository/archive?sha=master unzip -l foo.zip | head -10 ``` While requesting a direct SHA nests it under `project-sha-fullsha/`. (Test with:) ``` curl -o foo.zip https://gitlab.com/api/v4/projects/gitlab-org%2Fgitlab/repository/archive?sha=d27e4995814015252391c488d082d96935497e29 unzip -l foo.zip | head -10 ``` (Short SHAs are also accepted, generating `project-shortsha-fullsha`) This prefix generating behavior, while asserted in tests in the code, is not documented as an expected or stable behavior to users of the API that would end up relying on it. ### Proposal <!-- Further specifics for how can we solve the problem. --> We should document the various forms of prefixes one can expect when using this API. ### Who can address the issue <!-- What if any special expertise is required to resolve this issue? --> The developers maintaining the `archive_prefix` method inside `lib/gitlab/git/repository.rb` file should be able to vouch for the stability of the naming format. I couldn't find a direct codeowner map for that file or its immediate parent, but the Source Code group may be the right one. ### Other links/references <!-- E.g. related GitLab issues/MRs -->