Uniform approach to distributing important messages about Raku

[vrurg]

As it was recently discussed at a Raku Steering Council meeting, we don't have a common way to distribute important messages amount community members and Raku users in general. Those message could carry any kind of notifications: from important decisions to security alerts.

This issue could also be considered as a development of #246.

[nxadm]

advertisements about

[vrurg]

Proposal

Here is a solution I proposed at the meeting and would like it to be considered here and possibly accepted for implementation.

Tasks To Be Solved

• No limitation on kind of messages distributed. The only requirement for a notification to hit the system is for it to be considered important for the community.
• Easy access by public
• Priority/urgency levels
• Categorization of notifications (public, core development, etc.)
• Simpilicity

Solution

The implementation I propose is a Github repository under Raku organization. The repository's primary content would be text or markdown files containing notification messages. The directory structure of the repository would only consists of top-level directories named after full 4-digit years. The root directory would contain some number of auxiliary files like README.md and, perhaps, few special ones necessary to maintain the notifications. For example:

$ ls
2021/
2022/
README.md
meta.json

Categorization

Notifications can have three levels of importance:

• Emergency (mostly for security problems, but not only)
• Urgent
• Announcement

A notification can also be tagged to determine its desired audience and, correspondingly, the preferred channels of distribution. Say, the following standard tags could be supported initially:

• public – for anybody, including non-Raku people; namely, broadcasts
• community
• core

I barely see a reason to introduce any extra audience-related tags. And even if I overlooked something, it is better to stay limited to no more than 5 tags of this kind altogether.

Yet, the above doesn't mean no other tags are allowed as they may be helpful for cataloging purposes.

File Format And Content

As it was previously stated, only text or markdown formats are allowed.

A markdown format can include a Jekyll Front Matter section with importance level and tags:

---
level: announcement
tag: community
---
# We have news

News to be told...

Any announcement must start with a header line to be used by those distribution channels where displaying the full text is undesirable. Alternatively, the header could be represented with title keyword of the Front Matter section.

A text format is only accepted for cases where the notification has default level and tag. I my view those would be announcement and community as they're likely to be the most commonly used.

The first line of a text file is always considered as message title.

File Naming Convention

Any message file name must start with numeric date and UTC time of submission in YYYY-MM-DD-HH-MM format. Brief description may or may not follow after a space. .md or .txt extensions are mandatory.

Possible Usage

The repository would only serve as an authoritative source of information. The simplicity of accessing it and parsing the textual formats of submitted notifications would make it rather simple to re-distribute them over any kind delivery channel:

• mailing lists
• social networks (tags can be used for hashtagging)
• specialized utilities
• ...

Github actions can be used to implement immediate publishing.

Submission

New notifications are to be submitted via PR process.

[ugexe]

As far as how things would consume this I would expect a simple, single endpoint (or an endpoint-per-topic) that contains some number of messages. Tooling that consumes this then does not need to know about e.g. git, just how to read whatever remote file(s) might be of interest (because unlike git, Windows has the tools for fetching remote files already installed). Of course the repository could still be populated and structured as suggested, but then there should be some automation that generates the /foo-notifications.txt file in the repo (which can be served by github) or endpoint (which lives somewhere to just map /foo-notifications.txt to the current YYYY-MM-DD.txt).

As far as the format we should consider something that allows for either no dependencies or for a copy-paste type dependency (like an INI grammar). For instance when a tool like zef reads /foo-notifications.txt how would it filter the number of messages it consumes, and/or filter the types of notifications based on user configuration? A naive solution would be a message-per-line, with parts of the message separated by | (so like security|2022-12-1|This is an important security message\nsecurity|2022-11-2|This is an older important security message\n", such that a parser is basically just $file.IO.lines.map(*.split("|", 3))

[vrurg]

@ugexe Makes full sense. I don't see it as a part of the specification as it more on the implementation detail side of the things.

Moreover, it might be possible to "wrap" the repo into some kind of static generator (Jekyll?) and publish on github.io. It would make it possible to implement RSS/Atom feeds too.

[CIAvash]

I've been bringing up #158 in discussions in vain, but with Hugo you can achieve this as well. With Taxonomies for [custom] tags or categories and Data Templates for storing JSON, YAML, XML and TOML data in the data directory and retrieving them in a template or even fetching remote JSON and CSV content.

And of course you can have RSS/Atom feeds for them too.

Just thought it wouldn't hurt to mention it.