111 lines
4.6 KiB
Plaintext
111 lines
4.6 KiB
Plaintext
|
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/<channel-id>/news
|
||
|
|
|
||
|
|
- Component-related news items, located in
|
||
|
|
/channel/<channel-id>/component/<component-id>/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/<channel-id>/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
|