From 3076555b047fd7f48e8ad20b3592aaf997de5482 Mon Sep 17 00:00:00 2001 From: Max Wash Date: Mon, 7 Jul 2025 13:57:47 +0100 Subject: [PATCH] doc: add sample repository directory; repo layout documentation --- doc/repo-format.txt | 10 ++ .../vanilla/component/universe/index.json | 4 + .../vanilla/component/universe/packages.json | 0 .../vanilla/component/universe/release.zst | 0 doc/sample-repo/channel/vanilla/index.json | 0 doc/sample-repo/index.json | 8 ++ doc/sample-repo/news/20250707.01.news | 110 ++++++++++++++++++ 7 files changed, 132 insertions(+) create mode 100644 doc/repo-format.txt create mode 100644 doc/sample-repo/channel/vanilla/component/universe/index.json create mode 100644 doc/sample-repo/channel/vanilla/component/universe/packages.json create mode 100644 doc/sample-repo/channel/vanilla/component/universe/release.zst create mode 100644 doc/sample-repo/channel/vanilla/index.json create mode 100644 doc/sample-repo/index.json create mode 100644 doc/sample-repo/news/20250707.01.news diff --git a/doc/repo-format.txt b/doc/repo-format.txt new file mode 100644 index 0000000..175d226 --- /dev/null +++ b/doc/repo-format.txt @@ -0,0 +1,10 @@ +Root directory contents: + - index.json: Describes the repository, including it's name, description, available channels, the system for which it provides packages, etc. + - news: Contains news items. The latest news will be shown to the user when they next refresh their package database. + - pool: Contains all the raw package files. If multiple channels provide the same package version/arch, both will point to the same package file within the pool. + - channel: The channels that this repository provides. + + +/pool directory contents: + - One directory for each letter of the alphabet, plus an extra set of directories for each letter of the alphabet prefixed with 'lib'. + When a package is added to the repository, it is stored in one of these subdirectories. Which one depends on the first letter of the package name. diff --git a/doc/sample-repo/channel/vanilla/component/universe/index.json b/doc/sample-repo/channel/vanilla/component/universe/index.json new file mode 100644 index 0000000..23eab41 --- /dev/null +++ b/doc/sample-repo/channel/vanilla/component/universe/index.json @@ -0,0 +1,4 @@ +{ + "name": "Universe", + "description": "Officially-supported open-source packages." +} diff --git a/doc/sample-repo/channel/vanilla/component/universe/packages.json b/doc/sample-repo/channel/vanilla/component/universe/packages.json new file mode 100644 index 0000000..e69de29 diff --git a/doc/sample-repo/channel/vanilla/component/universe/release.zst b/doc/sample-repo/channel/vanilla/component/universe/release.zst new file mode 100644 index 0000000..e69de29 diff --git a/doc/sample-repo/channel/vanilla/index.json b/doc/sample-repo/channel/vanilla/index.json new file mode 100644 index 0000000..e69de29 diff --git a/doc/sample-repo/index.json b/doc/sample-repo/index.json new file mode 100644 index 0000000..4274322 --- /dev/null +++ b/doc/sample-repo/index.json @@ -0,0 +1,8 @@ +{ + "name": "Sample Repository", + "description": "Official Sample Repository", + "system": "sample", + "arch": [ "amd64" ], + "channel": [ "vanilla" ], + "newsItems": [ "20250707.01" ] +} diff --git a/doc/sample-repo/news/20250707.01.news b/doc/sample-repo/news/20250707.01.news new file mode 100644 index 0000000..0bea577 --- /dev/null +++ b/doc/sample-repo/news/20250707.01.news @@ -0,0 +1,110 @@ +PublishDate: 2025-07-07 09:00:00 +Importance: Normal +Title: Welcome to the Rosetta Package Manager +Category: General + ++------------------------------------------------------------------------------+ +| Welcome to the Rosetta Package Manager! | ++------------------------------------------------------------------------------+ + + This is a sample news item to introduce you to the Rosetta package manager. + These news items can be used to provide information and updates to those who + use your repository. + + +1 News File Location +==================== + + News items come from four different sources: + - Repository-wide news items, located in /news + + - Channel-related news items, located in /channel//news + + - Component-related news items, located in + /channel//component//news + + - Package-related news items, included in individual package files. + + Specific news items can be published in different locations depending on who + the news is relevant for. For example, if there is some critical issue that + affects all users of a repository, /news would be the perfect place to use. + If, instead, the issue only affects users of a particular channel (maybe + you have a channel for each release of your operating system), + /channel//news would be more appropriate. It's important that + news is targeted to the appropriate audience so that users don't have to sift + through news that isn't relevant to them. + + +2 News File Format +================== + + News items have a specific plain-text format, which can be seen in this file. + The file begins with a set of headers that describe certain attributes of the + news, followed by the news content and an optional footer. + + + 2.1 Header And Footer + --------------------- + + These headers include: + - PublishDate: The date and time on which the news item was published. This + is used by clients to determine which news items have been released since + the user last checked the news. This is always in UTC. + + - Title: The title of the news item. + + - Category: The particular category that the news item is relevant to. + Possible values include: + * General + * Security + + - Importance: How important it is that the user reads this news. + Possible values include: + * Low + * Normal + * High + * Critical + The user has to go out of their way to read Low and Normal news items, while + High and Critical news items will be shown automatically when the user next + interacts with the relevant part of the repo. + + Immediately following these headers are two line-feed characters. This + denotes the end of the header and the start of the content of the news files. + With two line feeds, there should be exactly one blank line visible between + the last header line and the first content line. + + At the end of the file is a line with 5 asterisk (*) characters. This denotes + the end of the of the news file's content and the start of the footer. Beyond + this point, you can put extra data, such as the vim formatting commands + visible in this file, that you don't want shown to the user. If no footer is + required, the 5-asterisk marker can be omitted, and the news content will + simply end where the file ends. + + + 2.2 Content + ----------- + + Between the header and footer is the actual news content that is shown to the + user. This section can be formatted in any way you prefer; any plaintext is + acceptable. This news file has been formated in a particular way to provide + example formatting that you may wish to use. It features a page header, + section and sub-section headings, and list formatting. All paragraphs + are indented with three spaces. The gap between a list item marker + and list item text is two spaces, with any following lines in that particular + list item indented with three spaces. There is one blank line between each + paragraph, and two blank lines between the last line in one section and + the heading of the next. + + The only formatting rule that should be adhered to is that, like code, lines + should be kept to no longer than 80 characters. This is due to the fact that + the vast majority of users will be viewing news items within their terminal + as they are using the ropkg commands, and 80 cells is the standard width for + terminal displays. + + Don't forget that, if your text editor supports in-line formatting directives + like vim, you can store these directives in the page footer so that they + aren't shown to the user. + +***** + +vim: shiftwidth=3 expandtab