kopoli/helm-grepint

Remove layers of history from documentation?

Closed this issue · 5 comments

rrthomas commented

Independent of the per-version defaults configuration, I think it's confusing to have historically-layered documentation; that is what release notes are for. I guess I'd move the current change history from the sources to a separate ChangeLog or similar). I'd be happy to make a patch to remove references to different versions from the main documentation if you agree (except where they refer to the version-based configuration options).

[Comment updated to reflect my realising that README.md is a generated file!]

kopoli commented

It would be very good to update the Description -part of the Commentary to remove the version layers.

Regarding the Changes -part:

  • The reason for that to be in the Commentary is that when this package is received through MELPA, this file is the only one that is received. I.e. git log is not visible there.
  • Having a changes -part in the Commentary is quite rare in Emacs packages, but I think I modeled it after el-get,which looks a bit similar.
  • Having separate readmes and changelogs is a bit against MELPA contributing guidelines: https://github.com/melpa/melpa/blob/master/CONTRIBUTING.org
    • IIUC this is because information would be lost as user may not be able to find it (from a separate file somewhere under .emacs.d).
    • Having the README.md generated from the package is only for displaying the information in Github.
  • One problem with the section is that it is out-of-sync with the authoritative changelog, git commits. I was thinking of only listing more major changes (changes only for major and minor version bumps, ignoring patch-level) in the future.

Regarding the generating the README.md:

  • It can be done with the command (link for the script is at the bottom of the README):
emacs --script make-readme-markdown.el < helm-grepint.el > README.md
  • It needs to be changed manually a bit: It adds the -*- lexical-binding: t -*- as part of the title.
kopoli commented

I did some clarifying of the Commentary section in commit d22947c.

Hopefully it is a bit less convoluted.

rrthomas commented

That's better; thanks!

rrthomas commented

I think this issue can be closed?

kopoli commented

Yeah, let's close this.

Thanks!