Overview

News items are published and delivered to users as follows:

1. A news item is written. The format to be used is described in News Item File Format.
2. The news item is reviewed, following the process described in News Item Quality Control.
3. The news item is committed to a CVS (or Subversion [8]) repository. From here, it is merged with the rsync tree. This is described in News Item Distribution.
4. The news item is merged with the rsync tree. Implementation details of this point are beyond the scope of this GLEP; existing solutions are in place for merging GLSAs to the tree.
5. Users fetch the news item when they sync. This ensures that the news items in question are pushed to the user before the user accidentally makes an unwanted change. No changes to the existing rsync process are required by this GLEP.
6. Portage filters the news item and, if it is relevant, installs it in a special location to be read by a news item reader. Messages are also displayed to inform the user that news is available.
7. The news item is handled by the user's choice of news item reader. See News Item Clients.

News Item File Format

Each news item will be represented by a single text file. This file will be encoded using UTF-8 for compatibility with and for the same reason as existing Gentoo documentation [1] and tree [6] practices.

The news item will be named in the form yyyy-mm-dd-item-name.en.txt, where item-name is a very short name (e.g. apache-updates) and en is the two letter ISO 639 [9] language code for the news item. The short name must consist only of characters a-z, A-Z, 0-9 and - (hyphen).

News items may be signed using GPG. If this is done, a detached signature should be used.

The directory and file name rules are designed specifically to allow easy sorting by date.

An English (en) version must be available for all news items. Other languages may be provided either by the original author or by other translators who have commit access. This anglocentricity is justified on the grounds that nobody objected to it with GLEP 34 [7].

A news item's content will consist of an RFC 822 [11] style header followed by the main body of the message as plain text. This GLEP defines various optional and mandatory headers. Future GLEPs may propose new headers -- tools handling these news items must ignore any unrecognised header.

Title: YourSQL Upgrades from 4.0 to 4.1
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Content-Type: text/plain
Posted: 01-Nov-2005
Display-If-Installed: <dev-db/yoursql-4.1_alpha

YourSQL databases created using YourSQL version 4.0 are incompatible
with YourSQL version 4.1 or later. There is no reliable way to
automate the database format conversion, so action from the system
administrator is required before an upgrade can take place.

Please see the Gentoo YourSQL Upgrade Guide for instructions:

    http://www.gentoo.org/doc/en/yoursql-upgrading.xml

Also see the official YourSQL documentation:

    http://dev.yoursql.com/doc/refman/4.1/en/upgrading-from-4-0.html

After upgrading, you should also recompile any packages which link
against YourSQL:

    revdep-rebuild --library=libyoursqlclient.so.12

The revdep-rebuild tool is provided by app-portage/gentoolkit.

News Item Quality Control

There have been complaints regarding the comprehensibility of some upgrade notices and news items in the past. This is understandable -- not every Gentoo developer speaks English as a first language. However, for the sake of clarity and professionalism it is important that any language problems be corrected before inflicting a news item upon end users.

Thus, all proposed news items must be posted to the gentoo-dev or gentoo-core mailing list, and Cc:ed to pr@gentoo.org at least 72 hours before being committed (exceptions may be made in exceptional circumstances). Any complaints regarding wording or clarity must be addressed before the news item goes live.

News items must only be for important changes that may cause serious upgrade or compatibility problems. Ordinary upgrade messages and non-critical news items should remain in einfo notices. The importance of the message to its intended audience should be justified with the proposal.

News Item Distribution

* Important: 3 config files in /etc need updating.
* Type emerge --help config to learn how to update config files.

* Important: there are 5 unread news items.
* Type emerge --help news to learn how to read news files.

News Item Clients

Once a news item is 'installed', third party tools (or a traditional Unix pager and rm) can be used to display and view the news files. An eselect [2] module shall be created as the 'suggested' display tool; other display tools (for example, a news to email forwarder, which would be ideal for users who sync on a cron) are left as options for those who desire them -- the simple file format make this relatively simple.

News Item Removal

News items can be removed (by removing the news file from the main tree) when they are no longer relevant, if they are made obsolete by a future news item or after a long period of time. This is the same as the method used for updates entries.

Portage Code

TODO

Simple eselect News Client

A demonstration eselect news display script follows:

# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id: glep-0042.html,v 1.3 2005/11/07 22:26:59 ciaranm Exp $

DESCRIPTION="Read important Gentoo news items"
MAINTAINER="ciaranm@gentoo.org"
SVN_DATE='$Date: 2005/11/07 22:26:59 $'
VERSION=$(svn_date_to_version "${SVN_DATE}" )

get_news_item_list() {
    [[ -d "${ROOT}/var/lib/gentoo/news" ]] || return
    (
       local news
       for news in "${ROOT}/var/lib/gentoo/news/"*.txt ; do
           echo $(basename ${news%%.*} )
       done
    ) | sort -u
}

get_filename() {
    local best_lang=${LANG%%_*} lang= filename="${1}"
    [[ -e "/${filename}" ]] || for lang in "${best_lang}" "en" ; do
        filename="${ROOT}/var/lib/gentoo/news/${1}.${lang}.txt"
        [[ -e "${filename}" ]] && break
    done
    [[ -e "${filename}" ]] && echo "${filename}" || die -q "Can't find '${1}'"
}

get_all_filenames() {
    if [[ -z "${1}" ]] ; then
        echo "${ROOT}/var/lib/gentoo/news/"*.??".txt"
    else
        echo "${ROOT}/var/lib/gentoo/news/${1}."??".txt"
    fi
}

get_headers() {
    sed -e '/^$/Q' < $(get_filename "${1}" )
}

get_body() {
    sed -e '1,/^$/d' < $(get_filename "${1}" )
}

get_title() {
    get_headers "${1}" | sed -n -e '/^[Tt]itle: /s/^[^:]\+:[ \t]*//p'
}

### list action

## {{{ list stuff
describe_list() {
    echo "List available news items"
}

do_list() {
    write_list_start "Available news items:"
    local empty=yes n=1
    for news in $(get_news_item_list ) ; do
        write_numbered_list_entry ${n} "$(highlight $(get_title ${news} ) ) (${news})"
        n=$(( n + 1 ))
    done
}
## }}}

## {{{ show stuff
describe_show(){
    echo "Show a news item"
}

do_show() {
    [[ -z "${1}" ]] && die -q "You didn't tell me which news item to read"

    local target=${1} filename=
    if is_number "${target}" && [[ ${target} -ge 1 ]] ; then
        targets=( $(get_news_item_list ) )
        target=${targets[$(( ${target} - 1 ))]}
    fi

    (
        get_headers "${target}" | grep -v '^Display-If-\|Content-Type:'
        echo
        get_body "${target}"
    ) | ${PAGER:-cat}
}
## }}}

# {{{ delete stuff
describe_delete() {
    echo "Delete a news item"
}

do_delete() {
    [[ -z "${1}" ]] && die -q "You didn't tell me which news item to delete"

    for target in $@ ; do
        if is_number "${target}" && [[ ${target} -ge 1 ]] ; then
            targets=( $(get_news_item_list ) )
            target=${targets[$(( ${target} - 1 ))]}
        fi

        rm $(get_all_filenames "${target}" ) || die -q "Couldn't delete ${target}"
    done
}
# }}}

# {{{ delete-all
describe_delete-all() {
    echo "Delete all news items"
}

do_delete-all() {
    rm $(get_all_filenames ) || die -q "Couldn't delete news items"
}
# }}}

Simple News to Mail Forwarder

A demonstration shell script which delivers news items via email follows:

#!/bin/bash

to_address="root@localhost"
mail="mailx"
best_lang="${LANG%%_*}"

for news in /var/lib/gentoo/news/*.*.txt ; do
    [[ -z "${best_lang}" ]] || news="${news%%.*}.${best_lang}.txt"
    [[ -f "${news}" ]] || news="${news%%.*}.en.txt"
    [[ -f "${news}" ]] || continue
    title=$(sed -n -e '/^Title:/ { s,^[^:]\+:[ \t]\+,,p ; q }' < ${news} )
    sed -e '1,/^$/ { /^Display-If\|Content-Type/d }' < "${news}" | \
        ${mail} -s "Gentoo news: ${title}" "${to_address}" && \
        for file in ${news%%.*}.*.txt ; do rm "${file}" ; done
done