Enhance page.

Some formatting changes.  Add some further content of other emails of mine
(bug-hurd, 2009-07-07, <20090707171015.GX23964@fencepost.gnu.org>, and
2009-07-09, <20090709091037.GY23964@fencepost.gnu.org>).

1 files changed, 70 insertions, 25 deletions

diff --git a/contributing/web_pages/news.mdwn b/contributing/web_pages/news.mdwn
index f365bc79..d6e25b87 100644
--- a/contributing/web_pages/news.mdwn
+++ b/contributing/web_pages/news.mdwn
@@ -8,47 +8,92 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled [[GNU Free Documentation
 License|/fdl]]."]]"""]]
 
-[[!meta title="HowTo prepare and publish 'a month of the Hurd' for the next month"]]
+[[!meta title="""How to prepare and publish "a month of the Hurd" for the last
+month"""]]
 
-We prepare the month of the Hurd in a public git branch (master-news_next) and merge it once we want to publish the news. 
+We prepare *a month of the Hurd* in a public git branch (`master-news_next`),
+and merge that one into `master` once we want to publish the news.  The idea is
+to record to-be-published changes on that branch at they time they arise, and
+then publish them en bloc at the end of the month.
 
-For practical work that means, we use the following commands: 
+As this is done on a separate branch, there are two options: you can have
+separate repositories (*clones*, or *checkouts*; what you get from `git clone`)
+for the `master` and `master-news_next` branches, or you can deal with both in
+the same repository.  Having separate repositories you don't have to remember
+which branch you're on, and don't have to switch between branches before
+beginning to edit files, and it doesn't matter -- as no switching between
+branches is needed -- if you have uncomitted changes to some files.  On the
+other hand, you may want to keep it all in one repository, to save disk space,
+and for shuffling different branches' commits being (a bit) easier.
 
-* create a local branch for news_next
+For practical work that means to use the following commands: 
 
-        git fetch && git checkout -b master-news_next origin/master-news_next
+  * create a local branch for `master-news_next`
 
-* get the latest version of news_next when you already created a local version of the branch
+        $ git fetch
+        $ git checkout -b master-news_next origin/master-news_next
 
-        git fetch && git checkout master-news_next 
+      * if you already have created a local branch `master-news_next`: update to
+        the latest version of it
 
-Always do check which branch you're on (asterisk in the first column of
-``git branch'''s output), and only then begin to do your changes and
-commit them.
+            $ git checkout master-news_next
+            $ git pull --rebase
 
-* create a new news entry
+  * edit
 
-        cp news/yyyy-mm-dd.mdwn news/YYYY-MM-DD.mdwn
-        (edit the new file)
-        git add news/YYYY-MM-DD.mdwn
-        git commit -m "Begun the news entry for YYYY-MM-DD."
+    Always do check which branch you're on (asterisk in the first column of
+    `git branch`'s output), and only then begin to do your changes and commit
+    them.
 
-(just copy the most recent news file)
+    We should not update news items that have already been published (that is,
+    on <http://www.gnu.org/software/hurd/news.html>; no problem for the
+    [[staging area|web_pages#staging_area]]), as the system will always also
+    update the RSS feeds, etc., causing the old news item to reappear on feeds,
+    which is a bit of a nuisance.
 
-* check the outgoing changes
+      * at the beginning of a month: create a new news entry
 
-        git log --reverse -p -C origin/master-news_next..master-news_next
+            $ cp news/2009-06-30.mdwn news/YYYY-MM-DD.mdwn
+            $ # edit the new file
+            $ git add news/YYYY-MM-DD.mdwn
+            $ git commit -m "Begun the news entry for YYYY-MM-DD."
 
-* push the changes
+        That is, use the *2009-06-30* news snippet as a template for the new
+        one.
 
-        git push origin master-news_next:master-news_next
+  * check the outgoing changes
 
-* if push fails, pull and rebase
+        $ git log --reverse -p -C origin/master-news_next..master-news_next
 
-        git pull --rebase
+  * push the changes
 
-* publish the news
+        $ git push origin master-news_next
 
-        git checkout master && git merge master-news_next
+      * if push fails, pull and rebase the local changes on top of the remote
+        changes
 
-That means, for publishing we merge master-news_next into master. 
+            $ git pull --rebase
+
+        This will only happen if someone else has been installing commits into
+        `origin`'s `master-news_next` branch since the last time you
+        synchronized to it.
+
+        Note that this might cause some conflicts to arise -- if the remote
+        repository contains commits that conflict with any that you've been
+        recording in your local repository.  For this reason, you might want to
+        already do this *rebase* before beginning you local edits, simply to
+        shorten the time frame in which such conflicts can arise.
+        (Theoretically, in the very rare case of very much concurrent editing
+        going on, you'd have to repeat this again (and again...) before
+        succeeding to push your changes.)
+
+  * at the end of the month: publish the news
+
+        $ git checkout master
+        $ git pull --rebase
+        $ git merge master-news_next
+        $ git push origin master
+
+    That means, for publishing we merge `master-news_next` into `master`.
+    After that merge, work for the next month's news item can continue on
+    `master-news_next`.