152 lines
6.3 KiB
Plaintext
152 lines
6.3 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
|
|
==================
|
|
|
|
The news file has a specific plain-text format, which can be seen in this file.
|
|
|
|
|
|
2.1 General Layout
|
|
------------------
|
|
|
|
The news file contains one or more news items. Each news item begins with
|
|
a header section describing the news item, followed by a content section
|
|
containing the actual news content. At the end of the last news item is an
|
|
optional footer section.
|
|
|
|
|
|
2.1 Header
|
|
----------
|
|
|
|
Each news item begins with a standardised header section describing it. A
|
|
range of header items are supported.
|
|
|
|
These 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, and is formatted
|
|
as: YYYY-MM-DD HH:NN:SS
|
|
where:
|
|
* YYYY is the current year.
|
|
* MM is the current month number, with a leading 0 if less than 10.
|
|
* DD is the current day of the month, with a leading 0 if less than 10.
|
|
* HH is the current hour of the day, between 0-24, with a leading 0 if
|
|
less than 10.
|
|
* NN is the current minute of the hour, between 0-59, with a leading 0 if
|
|
less than 10.
|
|
* SS is the current second of the minute, between 0-59, with a leading 0
|
|
if less than 10.
|
|
|
|
- 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
|
|
-----------
|
|
|
|
Following the header 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.
|
|
|
|
The end of the news content is marked by two line feed characters, followed
|
|
by five asterisk characters. If this is the last news item in the file, no
|
|
end marker is required; the end of the file implicitly marks the end of the
|
|
final news item.
|
|
|
|
|
|
2.3 Footer
|
|
----------
|
|
|
|
The footer is an optional part of the news file, located at the very end. It
|
|
can be used for data that shouldn't be shown to the user. For example, if you
|
|
use vim to write your news files, you can include vim in-line formatting
|
|
directives in the footer to make writing the news file easier, without them
|
|
being visible to the user.
|
|
|
|
Of course, it is up to the program displaying the news item to respect these
|
|
visibility rules, so while the data in the footer is (ideall) not visible, it
|
|
is still always public.
|
|
|
|
To add a footer to your news file, use a footer marker at the end of the last
|
|
news item in the file. The footer marker is the same as the content end
|
|
marker (two linefeeds, followed by five asterisks), but with an additional
|
|
exclamation mark immediately following the fifth asterisk.
|
|
|
|
*****!
|
|
|
|
vim: shiftwidth=3 expandtab
|