Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove layers of history from documentation? #11

Closed
rrthomas opened this issue Jul 3, 2020 · 5 comments
Closed

Remove layers of history from documentation? #11

rrthomas opened this issue Jul 3, 2020 · 5 comments

Comments

@rrthomas
Copy link
Contributor

rrthomas commented Jul 3, 2020

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
Copy link
Owner

kopoli commented Jul 4, 2020

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
Copy link
Owner

kopoli commented Jul 7, 2020

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

Hopefully it is a bit less convoluted.

@rrthomas
Copy link
Contributor Author

rrthomas commented Jul 7, 2020

That's better; thanks!

@rrthomas
Copy link
Contributor Author

I think this issue can be closed?

@kopoli
Copy link
Owner

kopoli commented Jul 11, 2020

Yeah, let's close this.

Thanks!

@kopoli kopoli closed this as completed Jul 11, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants