emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Organizing the NEWS file a bit better


From: Stefan Kangas
Subject: Re: Organizing the NEWS file a bit better
Date: Mon, 6 Sep 2021 04:30:56 +0200

Lars Ingebrigtsen <larsi@gnus.org> writes:

> > I'm looking at re-organizing NEWS a bit, and I'm not sure how we prefer it.
> >
> > In general, I guess I also wonder if anyone will protest if I take it
> > upon myself to move things around to more sensible places.
>
> Please go ahead.

I have now pushed my reorganization of the NEWS file to master.

Note that the changes were necessarily extensive, as a large portion
of that file was in completely the wrong place, or at worst seemed to
have been placed almost at random.  This is not to criticize anyone,
but really it just looks like the file started getting messy at some
point and then it snowballed from there.

None of the changes should be controversial, as it was just a matter
trying to ensure we have some basic level of organization in the file.
I've decided to push what I have so far, because I need a pause from
this, and I don't want master to diverge too much from what I have.

I tried to follow some general principles, for example:

- Avoid editing beyond moving things around, unless the edits are very,
  very light.

- Add subsections where it makes sense.  Remove them where it doesn't.

- Put the most notable changes as early as possible.  For example,
  under "Changes in Emacs 28.1" I have a new subsection
  "Miscellaneous" that has many bits and pieces that I didn't feel
  deserve a place at the top.  But I moved NonGNU ELPA to the very
  top.

- Put obviously less used or less important things last.  For example,
  I put Bindat at the end of "Lisp Changes" as it is only used by a
  small number of packages.

- Put related things close whenever possible.

Some of this is by nature subjective.  I did the work, so I got to
decide (yay!) but if you feel like I made a mistake or wrote some
important feature off or something, please shuffle things around to be
better.

I tried hard to ensure nothing was lost,[1] but if you want to check
this yourself you could use, e.g.:

    comm -3 <(git show HEAD^:etc/NEWS|sort) <(sort etc/NEWS)

If anyone wants to review my changes in full, I suspect you will find
the diff to be very hard to read.  It might be easier to just read the
new file and compare it to the old one.

Reviews are welcome, preferably in the form of just pushing any
further changes to master.

Footnotes:
[1] I have advocated in the past for marking documentation changes
     using org-mode style tags.  This would mean that you add a tag
     like ":DOC:" on the same line as a headline, instead of "+++" on
     the line before.  That way, one could edit the file using
     'outline-move-subtree-{up,down}'.  That would have made this
     reorganization quite a bit easier.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]