New changelog conventions

[sjsrey]

This is modeled after how to keep a changelog .

Opening up for discussion of conventions for how to keep our changelogs across the federation, using libpysal as a test case.

[codecov[bot]]

Codecov Report

Merging #505 (94ec7b5) into master (8286c8f) will decrease coverage by 0.1%. The diff coverage is n/a.

@@           Coverage Diff            @@
##           master    #505     +/-   ##
========================================
- Coverage    78.8%   78.7%   -0.1%     
========================================
  Files         122     122             
  Lines       13100   13185     +85     
========================================
+ Hits        10320   10374     +54     
- Misses       2780    2811     +31     

Impacted Files	Coverage Δ
libpysal/examples/remotes.py	74.4% <0.0%> (-21.4%)	:arrow_down:
libpysal/weights/contiguity.py	77.2% <0.0%> (-1.9%)	:arrow_down:
libpysal/examples/base.py	58.9% <0.0%> (-1.1%)	:arrow_down:
libpysal/weights/distance.py	85.4% <0.0%> (ø)
libpysal/weights/tests/test_weights.py	99.7% <0.0%> (+<0.1%)	:arrow_up:
libpysal/weights/weights.py	82.8% <0.0%> (+0.1%)	:arrow_up:
libpysal/weights/tests/test_contiguity.py	95.1% <0.0%> (+0.3%)	:arrow_up:
libpysal/_version.py	40.7% <0.0%> (+2.7%)	:arrow_up:
libpysal/weights/gabriel.py	47.1% <0.0%> (+3.3%)	:arrow_up:

[sjsrey]

To avoid conflicts in the changelog, we might add a digest directory in the repo. In there we add a digest entry for each PR that we want to highlight in the changelog.

---
category: added
description: "No longer polling remotes on init"
d_url: https://github.com/pysal/libpysal/pull/504
contributor: sjsrey
c_url: https://github.com/sjsrey
status:

We add tooling that globs the digest directory for all entries that have empty status. Each such entry is parsed and added to the [Unrleased] section and category of the changelog.md file. For this entry the result would be something like:

# Changelog

## [Unreleased]
https://github.com/pysal/libpysal/compare/v4.7.0...master

### Added

- W.from_WSP
- W.to_sparse

### Changed
- [No longer polling remotes on init](https://github.com/pysal/libpysal/pull/504) [@sjsrey](https://github.com/sjsrey/)

After the changelog is updated, the digest entry gets updated: status: logged.

---
category: added
description: "No longer polling remotes on init"
d_url: https://github.com/pysal/libpysal/pull/504
contributor: sjsrey
c_url: https://github.com/sjsrey
status: logged

Release

When it comes time to do the release, the changelog.md file goes from:

# Changelog

## [Unreleased]
https://github.com/pysal/libpysal/compare/v4.7.0...master

### Added

- W.from_WSP
- W.to_sparse

### Changed
- [No longer polling remotes on init](https://github.com/pysal/libpysal/pull/504) [@sjsrey](https://github.com/sjsrey/)

to

# Changelog

## [Unreleased]
https://github.com/pysal/libpysal/compare/v4.8.0...master



## [4.8.0](2023-01-12)

### Added

- W.from_WSP
- W.to_sparse

### Changed
- [No longer polling remotes on init](https://github.com/pysal/libpysal/pull/504) [@sjsrey](https://github.com/sjsrey/)

And we continue on post-release with the [Unreleased] version sections getting automatically populated with PRs and their digest entries.

This is a blend of curation (digests) and automation.

[sjsrey]

At the Jan-23 dev meeting, we decided to drop the digest idea and instead keep the ## [Unlreased] heading. The latter will contain entries that come with Pull Requests that we want to publicize in a future release.

The PR template likely needs adjusting to reflect this.

[sjsrey]

It would be great to standardize the changelogs across all pysal packages.

Building on the work @jGaboardi has done with ghactions, I think we can come up with a mapping of labels -> categories to get automated changelogs and release notes that are the same structure across the packages.

I re-added the WIP label so we can have a discussion of this to flesh the design out here.

[sjsrey]

We can add labels to already merged PRs, so this could be done now with an eye towards the meta release and aggregating across the packages.

[jGaboardi]

Always willing to try something new for a better user experience.

[sjsrey]

Perhaps the new effort out of the scientific-python changelist is what we should use instead of rolling our own?

[knaaptime]

closing as we've had this implemented in the system for awhile and forgot to close the loop