Re: Re-including rst.el into Emacs repository

[Stefan Monnier]

> Well, how to bring this large "patch" into the Emacs repository?
> Usually in Free Software projects it's a best practice to submit small
> patches.  In this case this really makes no sense - the diff consists
> of 288 hunks.  May I commit simply the current version to Bazaar or is
> there a better way?  Also a review of the current version by you may
> make sense.

It's basically just a merge, so I don't see any need to do it in more
than a single commit.  But please try to keep some reference to the
"common ancestor" and "tip" of the branch being merged (that's done
automatically as Bzr metadata when it's a normal merge, but I suspect in
your case the branch from which you merge is external).

> According to the GNU Coding Standards I need to write a ChangeLog
> entry. I don't see this makes much sense for such a large patch - at
> least not in the way ChangeLog entries are done according to the GNU
> Coding Standards. So how to construct a ChangeLog entry which complies
> with the standards but makes sense?

Sometimes following the normal ChangeLog rules leads to surprisingly
manageable results even for large patches.  E.g. all new functions are
just listed as "new function" without any explanation of what they do,
so it can stay fairly concise (and even more so for new files, tho
I suspect in your case that won't help).

But if the normal ChangeLog is large, we usually try to shorten it with
things like "adjust all callers" which saves us from mentioning each one
of the callers when changing a calling convention or a function name.

Finally, I assume that you do have some kind of ChangeLog already (in
the form of a list of commit messages), so you might want to just
reformat those to fit the ChangeLog conventions and not spend too much
time making them concise: after all, it doesn't hurt much if the commit
message is more verbose than necessary.

> My work at rst.el also resulted in some new features. Where to put a
> description of these features? I think this will be most interesting
> for a new version of Emacs.

Put them in etc/NEWS.

> I also wrote a number of unit tests for some aspects of `rst.el`
> (nearly 6000 LOC) using the great `ert` framework.  I looked around
> a bit in the Emacs repository and discovered the `test` directory.
> Would this be the right place to put my tests to?

Yes.

> If so are there established practices for such a case?

Not very much yet.  You may want to take a look at
test/automated/Makefile to see if you can fit your changes within it.

> Since my tests need a buffer to operate on I also wrote some support
> code for ert to allow tests on buffer contents.  I didn't follow the
> development of ert - may be something like this exists meanwhile.  If
> not this may be useful for others, too.

Please submit the patch here (Cc'ing the ERT developer, of course).

> Finally a general question: On which mailing lists I am supposed to
> subscribe as an Emacs developer?  I just subscribed `emacs-devel` and
> `bug-gnu-emacs`.  Do I need to subscribe to `help-gnu-emacs` also?
> Any others?

It's largely up to you:
- emacs-devel is a good place to keep up with Emacs development.
- bug-gnu-emacs will let you see bug reports, including those about rst.el.
- help-gnu-emacs is for end-users, so if you want to help them out,
  that's great as well, but I think most Emacs maintainers don't keep
  track of that one very much.
- as someone else mentioned, there's also emacs-diffs to see
  the commits.
All of those are fairly high-traffic lists, tho; many maintainers of
packages who do not have a strong interest in participating in the
general development of Emacs might prefer not to subscribe to any of
those lists.  Hopefully, emacs-diffs will soon be auto-sent to
packages's maintainers so you get to see the commits made to your
package without having to receive all the commits, but how soon is
"soon" is yet to be determined.  Something similar for bugs would be
very helpful but it's not even "soon", AFAIK.


        Stefan