changelogdocutils

package
v0.22.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 5, 2022 License: Apache-2.0 Imports: 16 Imported by: 3

README

Changelog generation

These utils allow us to make our changelogs rich and easy-to-use for end users.

Note: changeloggenutils are currently only used in the user-facing changelogs on product sites. If you are looking for the code that generates changelogs on github releases, that lives under the changelogutils package.

The Problem

We fetch our changelog markdown from github release notes, which are in chronological ordering. As we often release bug fixes on backported branches, chronological ordering isn't the most intuitive for end users and often requires a non-trivial amount of scrolling to get to the desired changelog.

In addition, users often have a tough time finding out changes between different versions of our products. A changelog "diff tool" would be exteremely useful here, but can not be done without additional processing on the markdown release notes from github.

Changelog Gen Utils

These utils parse release notes from github and output a JSON which can be input to a javascript front-end, which will be part of the Solo.io Hugo theme used for the docs site. There are two "levels" of changelogs that are generated. These are described below.

minor_release.go

The minor release changelog generator groups changelogs by minor release. Here is an example of the structure of changelogs.

Opts:
  # These are options passed into the generator which are also in the output JSON
  # as metadata information for the front-end
  ...
ReleaseData:
  - v1.8.0:
    - v1.8.0-beta3:
        ...
    - v1.8.0-beta2:
        ...
  - v1.7.0:
      - v1.7.0-beta9:
       ...

The front-end is able to take this data and display it grouped by minor version with very little processing required.

merged_release.go

Many of our products have an open-source and enterprise component to them, split across multiple repos. Enterprise versions rely on open-source versions, and so trying to understand open-source changes between enterprise versions can get tricky. This is why we merge in open source changelog notes into the enterprise version notes.

Full structure of JSON:
{
  "Opts": {
    "NumVersions": 200,
    // "MaxVersion": semver,
    "MinVersion": "v1.0.0",
    "RepoOwner": "solo-io",
    "EnterpriseRepo": "gloo-edge-enterprise",
    "OpenSourceRepo": "gloo-edge"
  },
  "ReleaseData": [
    {
      // Top level release data has major version and minor version for grouping
      "v1.8.0": [
        {
          // Version data includes full version infformation
          "v1.8.0-beta3": {
            "Categories": {
              "Dependency Bumps": [
                {
                  "Note": "bumped k8s dep to v1.20"
                },
                {
                  // This note is from the open source repo, and thus has a FromDependentVersion field
                  "Note": "bumped go-utils dep to v1.6.4",
                  "FromDependentVersion": "v1.8.0-beta2"
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetMajorAndMinorVersion 

func GetMajorAndMinorVersion(v *Version) Version

func GetMajorAndMinorVersionPtr 

func GetMajorAndMinorVersionPtr(v *Version) *Version

func GetOtherRepoDepsBetweenVersions 

func GetOtherRepoDepsBetweenVersions(otherRepoReleasesSorted []Version, earlierVersion, laterVersion *Version) []Version

func SortReleaseVersions 

func SortReleaseVersions(versions []Version)

Sorts a slice of versions in descending order by version e.g. v1.6.1, v1.6.0, v1.6.0-beta9

Types

type ChangelogNotes 

type ChangelogNotes struct {
	Categories   map[string][]*Note
	ExtraNotes   []*Note
	HeaderSuffix string
	CreatedAt    int64
}

func NewChangelogNotes 

func NewChangelogNotes() *ChangelogNotes

func (*ChangelogNotes) Add 

func (c *ChangelogNotes) Add(other *ChangelogNotes)

func (*ChangelogNotes) AddWithDependentVersion 

func (c *ChangelogNotes) AddWithDependentVersion(other *ChangelogNotes, depVersion Version)

func (*ChangelogNotes) AddWithDependentVersionIncludeExtraNotes 

func (c *ChangelogNotes) AddWithDependentVersionIncludeExtraNotes(other *ChangelogNotes, depVersion Version)

func (*ChangelogNotes) Dump 

func (c *ChangelogNotes) Dump() (string, error)

type DependencyFn 

type DependencyFn func(*Version) (*Version, error)

func GetOSDependencyFunc 

func GetOSDependencyFunc(repoOwner, enterpriseRepo, osRepo, githubToken string) (DependencyFn, error)

HOF that returns a Dependency function. The returned function generates changelogs faster than the default but requires passing in the github token.

type MergedReleaseGenerator 

type MergedReleaseGenerator struct {
	// contains filtered or unexported fields
}

func NewMergedReleaseGenerator 

func NewMergedReleaseGenerator(opts Options, client *github.Client) *MergedReleaseGenerator

func NewMergedReleaseGeneratorWithDepFn 

func NewMergedReleaseGeneratorWithDepFn(opts Options, client *github.Client, depFn DependencyFn) *MergedReleaseGenerator

func (*MergedReleaseGenerator) GenerateJSON 

func (g *MergedReleaseGenerator) GenerateJSON(ctx context.Context) (string, error)

The merged release generator has 3 steps: 1. Fetches enterprise repo release notes 2. Gets open source dependency for each enterprise version 3. Merges open source release notes into enterprise version release notes

func (*MergedReleaseGenerator) GetMergedEnterpriseRelease 

func (g *MergedReleaseGenerator) GetMergedEnterpriseRelease(ctx context.Context) (*ReleaseData, error)

func (*MergedReleaseGenerator) GetOpenSourceDependency 

func (g *MergedReleaseGenerator) GetOpenSourceDependency(enterpriseVersion *Version) (*Version, error)

Enterprise changelogs have the option to "merge" open source changelogs. The following function retrieves and returns the open source version that an enterprise version depends on. It checks out the enterprise go.mod at the release version and looks for the open source dependency ({RepoOwner}/{DependentRepo}).

func (*MergedReleaseGenerator) MergeEnterpriseReleaseWithOS 

func (g *MergedReleaseGenerator) MergeEnterpriseReleaseWithOS(enterpriseReleases, osReleases *ReleaseData) (*ReleaseData, error)

type MinorReleaseGroupedChangelogGenerator 

type MinorReleaseGroupedChangelogGenerator struct {
	Client *github.Client
	// contains filtered or unexported fields
}

func NewMinorReleaseGroupedChangelogGenerator 

func NewMinorReleaseGroupedChangelogGenerator(opts Options, client *github.Client) *MinorReleaseGroupedChangelogGenerator

* Groups releases by their minor version: v1.8 - v1.8.2 - v1.8.1 v1.7 - v1.7.1 - v1.7.0-beta9 ...

func (*MinorReleaseGroupedChangelogGenerator) GenerateJSON 

func (g *MinorReleaseGroupedChangelogGenerator) GenerateJSON(ctx context.Context) (string, error)

Entry point for generating changelog JSON

func (*MinorReleaseGroupedChangelogGenerator) GetReleaseData 

func (g *MinorReleaseGroupedChangelogGenerator) GetReleaseData(ctx context.Context, cachedReleases []*github.RepositoryRelease) (*ReleaseData, error)

func (*MinorReleaseGroupedChangelogGenerator) NewChangelogNotes 

func (g *MinorReleaseGroupedChangelogGenerator) NewChangelogNotes(r *github.RepositoryRelease) (*ChangelogNotes, error)

func (*MinorReleaseGroupedChangelogGenerator) NewReleaseData 

func (g *MinorReleaseGroupedChangelogGenerator) NewReleaseData(releases []*github.RepositoryRelease) (*ReleaseData, error)

func (*MinorReleaseGroupedChangelogGenerator) NewVersionData 

func (g *MinorReleaseGroupedChangelogGenerator) NewVersionData() *VersionData

type Note 

type Note struct {
	Note string
	// Indicates which version of the dependent Repo that this note is from
	FromDependentVersion *Version
}

func ParseReleaseBody 

func ParseReleaseBody(body string) ([]*Note, map[string][]*Note, error)

func (*Note) MarshalJSON 

func (c *Note) MarshalJSON() ([]byte, error)

type Options 

type Options struct {
	// Github user/org
	RepoOwner,

	MainRepo,

	DependentRepo string
	// List of Github Repository Releases for the Main Repo
	MainRepoReleases []*github.RepositoryRelease
	// List of Github Repository Releases for the Dependent Repo
	DependentRepoReleases []*github.RepositoryRelease

	// NumVersions sets the maximum amount of releases to be fetched from Github.
	// Once fetched, MaxVersion and MinVersion are bounds for which versions are included
	// in the output. The following three only bound the
	NumVersions int
	// Maximum release version to be included in this changelog. If not specified, all releases >= MinVersion
	// will be included
	MaxVersion *Version
	// Minimum release version to display on this changelog. If not specified, all releases <= MaxVersion
	// will be included
	MinVersion *Version
}

type ReleaseData 

type ReleaseData struct {
	Releases map[Version]*VersionData
}

Release Data is mapped such that it easy to group by minor release e.g. Releases will be a map of v1.2.0 -> VersionData, v1.3.0 -> VersionData VersionData will contain information for individual Versions

func (*ReleaseData) GetChangelogNotes 

func (r *ReleaseData) GetChangelogNotes(v Version) (*ChangelogNotes, error)

func (*ReleaseData) GetReleasesSorted 

func (r *ReleaseData) GetReleasesSorted() []Version

func (*ReleaseData) MarshalJSON 

func (r *ReleaseData) MarshalJSON() ([]byte, error)

type VersionData 

type VersionData struct {
	ChangelogNotes map[Version]*ChangelogNotes
}

Contains Changelog enterpriseNotes for Individual openSourceReleases ChangelogNotes is a map of individiual openSourceReleases to enterpriseNotes e.g. v1.2.5-beta3 -> ChangelogNotes, v1.4.0 -> ChangelogNotes

func (*VersionData) MarshalJSON 

func (v *VersionData) MarshalJSON() ([]byte, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.