Feature: New Check: Check if the project has and maintains a CHANGELOG

[kehoecj]

Is your feature request related to a problem? Please describe.
No

Describe the solution you'd like
I would like to propose a new check to verify if a project has and maintains a CHANGELOG.md in the repo. This would be a LOW risk level check.

Proposed Scale:

3/10: Project has a CHANGELOG
5/10: 100% of releases have a CHANGELOG entry
7/10: 100% of releases and 50% of commits to main have a CHANGELOG entry
10/10: 100% of release and 90%+ of commits have a corresponding CHANGELOG entry

What is considered maintained:

• Each release has an entry in the changelog
• Each Github/Gitlab release has a corresponding changelog entry
• Most commits to main have a CHANGELOG entry

Reasons for inclusion:

1. Projects with a maintained CHANGELOG show maturity and consideration for release content
2. Changelogs make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. (from Keep a Changelog). They also show what changes have been merged to main since the previous release which is beneficial for contributors.

Reasons not to include:

1. Some overlap with the OpenSSF Best Practices badge
2. Projects have another mechanisms for providing human-readable release notes
3. Not strictly a security check

If approved, I would like volunteer to work this feature.

Describe alternatives you've considered
None

Additional context
N/A

[kehoecj]

@spencerschrock I'd like to work this issue but didn't want to start without some input from the code owners. Should I just go ahead and work this and submit a PR?

[spencerschrock]

Apologies, thanks for the ping.

In terms of inclusion for Scorecard, most checks have a security implication. However there is also desire for Scorecard to be used to measure OpenSSF baseline compliance. cc @GeauxJD

OSPS-BR-04 - All releases MUST provide a descriptive log of functional and security modifications.
Provide transparency and accountability for changes made to the project's software releases, enabling users to understand the modifications and improvements included in each release.

OSPS-BR-04.01
Requirement: When an official release is created, that release MUST contain a descriptive log of functional and security modifications.

Recommendation: Ensure that all releases include a descriptive change log. It is recommended to ensure that the change log is human-readable and includes details beyond commit messages, such as descriptions of the security impact or relevance to different use cases. To ensure machine readability, place the content under a markdown header such as "## Changelog".

I would try to think how we can frame the check/probe around these requirements

Each release has an entry in the changelog

This could be feasible, or each release notes could have a Changelog section as the baseline recommendation suggests.

Projects have another mechanisms for providing human-readable release notes

I think it would be good to do a quick enumeration before any implementation, just to see what we can realistically measure

Most commits to main have a CHANGELOG entry

This would be hard to measure, as Scorecard checks typically look only at file contents at a single commit. The commit data we currently have doesn't include a diff.

// Commit represents a Git commit.
type Commit struct {
	CommittedDate          time.Time
	Message                string
	SHA                    string
	AssociatedMergeRequest PullRequest
	Committer              User
}