search

OpenDataServices / developer-docs

Documentation about how we get our work done. For internal use, but happy to share
Other
1 stars 0 forks source link

What are the conventions around documentation / documenting changes for unversioned things? #95

Open ScatteredInk opened 2 years ago

ScatteredInk commented 2 years ago

See https://github.com/OpenDataServices/sphinx-base/issues/6 for an example of where our products are less useful/more time consuming to use because the documentation is out of sync with what the thing actually does.

The only documentation on documentation that I can see here relates to versioned libraries.

All repositories that are versioned using the scheme described on this page should keep a changelog. A file called CHANGELOG.md should be in the root of the repository.

This leaves a gap for things that aren't versioned, like the repo linked above.

Can we put something in place to ensure that people know what they can do with the things we make?

michaelwood commented 2 years ago

Ideally this case is covered with well written git commit messages + documentation of what the software does.

Maintaining a change log is often the same as selecting the git log by a version/commit range. So imo maintaining a change log file should be redundant in quite a lot of cases.

https://github.com/OpenDataServices/flatten-tool/compare/cac5de7b23c6320e94cd6b108217c8725d3c3926...92ca320d18301b13cdccb4783aacb5f07b580776

=

https://github.com/OpenDataServices/flatten-tool/compare/v0.17.0...v0.17.1