search

NixOS / nixpkgs

Nix Packages collection & NixOS
MIT License
18.19k stars 14.19k forks source link

nixos/doc/manual: incompatibilities are not reflected #32156

Open berce opened 6 years ago

berce commented 6 years ago

@nbp

Issue description

Backward incompatibilities as listed in the release notes are often not reflected in the manual. Users first read the deprecated documentation, and when it doesn't work, they might discover it's a known backward incompatibility.

Steps to reproduce

Search the manual for keywords in the backward incompatibilities section of the release notes.

e.g.: The release notes say "The postgres default dataDir has changed from /var/db/postgres to /var/lib/postgresql/$psqlSchema (...)" while the manual still contains "By default, PostgreSQL stores its databases in /var/db/postgresql."

Proposed solution

  1. For a new release, make it a requirement that the manual matches the backward incompatibilities.
  2. Go over all listed backward incompatibilities and check the manual. Most recent first.

I 'm willing to contribute to both. I started with PR #32143.

Should we create a pull request per modification, or group several commits in a single pull request?

nbp commented 6 years ago

Sorry for the late answer, I think creating one per issue is the best way to keep it updated, as these are likely contributed by different persons with different reviewers.

Feel free to do as you prefer, one per PR should be the best for reviewers. One big PR should imply that you will need multiple reviewers to double check all your commits, and might take more time to get everything merged without additional round-trips.

@globin Maybe this could be added to the release management check-list? i.e. to ping each person who added such backward incompatibility notice to double check examples in the documentation to ensure that all examples are still working as expected.

danbst commented 5 years ago

@berce sorry for big delay, fixed in https://github.com/NixOS/nixpkgs/commit/d54e52276bc381fd7093d44884fe4c6ad9629ad6 and backported

danbst commented 5 years ago

@lheckemann @disassembler what do you think about proposed solution? Is it doable in current release mgmt?

lheckemann commented 5 years ago

Yes, this makes a lot of sense IMO.

stale[bot] commented 4 years ago

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

  1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
  2. Ask on the NixOS Discourse.
  3. Ask on the #nixos channel on irc.freenode.net.