Skip to content

Latest commit

 

History

History
289 lines (221 loc) · 12.3 KB

release.md

File metadata and controls

289 lines (221 loc) · 12.3 KB
Raw

Releasing

How to release

Update Changelog and upgrading guide

Update the CHANGELOG.md by running make update-changelog VERSION=x.x.x-sumo-x.

Make sure the upgrading.md file has entries for the breaking changes for this release.

Create and push Git tag

In order to release a new version of Sumo OT distro you'd export TAG env variable and create a tag and push it.

This can be done using add-tag and push-tag make targets which will handle that for you as well as pushing tags for all the plugins in this repo so that they can be imported from other repositories.

export TAG=v0.75.0-sumo-0
make add-tag push-tag

NOTE:

Release build CI job is additionally using the prepare-tag make target in order to substitute the version placeholders in opentelemetry collector builder config so that the versions in the released binary match the repository tag.

If you'd like to build a binary to mimic the release binary you'd have to run that yourself like so:

make prepare-tag TAG=$(git describe --tags --abbrev=10 --match "v[0-9]*")

Remove tag in case of a failed release job

Pushing a new version tag to GitHub starts the release build jobs.

If one of these jobs fails for whatever reason (real world example: failing to notarize the MacOS binary), you might need to remove the created tags, perhaps change something, and create the tags again.

To delete the tags both locally and remotely, run the following commands:

export TAG=v0.75.0-sumo-0
make delete-tag delete-remote-tag

Publish GitHub release

The GitHub release is created as draft by the create-release GitHub Action.

After the release draft is created, go to GitHub releases, edit the release draft and fill in missing information:

  • Specify versions for upstream OT core and contrib releases
  • Copy and paste the Changelog entry for this release from CHANGELOG.md

After verifying that the release text and all links are good, publish the release.

Build packages

  1. Open the Build packages workflow in GitHub Actions for the sumologic-otel-collector-packaging repository.

  2. Click Run workflow.

  3. Enter the version of the release. (e.g. 0.83.0)

  4. Enter the Sumo version of the release. (e.g. 0)

  5. Click Publish release.

  6. Click Run workflow and wait fo the CI job to finish. Take note of the job number.

  7. After the release draft is created, go to GitHub Releases, find the release with the build iteration matching the CI job number, and then edit the release draft and fill in missing information:

  • Specify versions for upstream OT core and contrib releases
  • Copy and paste the Changelog entry for this release from CHANGELOG.md

After verifying that the release text and all links are good, publish the release.

Updating OT to next version

Here are the steps to update OT to next version:

  1. Update the version number where necessary
  2. Verify that Sumo OT distro builds correctly
  3. Fix lint and test errors
  4. Add missing upstream components
  5. Ensure all milestone tasks and issues have been done

Update OT version

Take note of the core and contrib versions you want to update to. They are often the same version (e.g. v0.77.0), but for some releases, these versions are different (e.g. v0.76.1/v0.76.3 or v0.78.2/v0.78.0).

Run:

make update-ot OT_CORE_NEW=x.x.x OT_CONTRIB_NEW=y.y.y

This make target also builds the Sumo OT distro binary to check that there are no build errors.

Fix lint errors and tests

Run:

make golint
make gotest

Check out the developer changelog

Contrib maintains a separate changelog for distribution maintainers and component authors. Check this for any changes that may affect our components or distribution. One example of this is increases to the minimal supported Go version.

Add missing upstream components

We include all of the components from the following list which are at least in alpha stability level:

Additionally, the following components are supported:

As a fourth step, please check OpenTelemetry Collector and OpenTelemetry Collector Contrib release pages for new components and update builder configuration and README.md if they are any. New exporters should not be added without a reason. Please consider example pull request: #604

Adding components from scratch

This shouldn't be required as long as list of components is regularly updated, but in case you want to generate full list of components, the following instruction can be helpful:

  1. update builder configuration You can use the following snippet inside OpenTelemetry Contrib repository in order to get list of components:

    export TAG=vx.y.z
git fetch --all
git checkout "${TAG}"
for dir in receiver processor extension; do
  echo "###############${dir}s###############"
  for file in $(ls "${dir}"); do
    echo "  - gomod: \"github.com/open-telemetry/opentelemetry-collector-contrib/${dir}/${file} ${TAG}\"";
  done;
done;

  2. Run make build in order to generate updated components file (otelcolbuilder/cmd/components.go)

  3. Update markdown table:

    1. Prepare local/receiver.txt, local/exporter.txt, local/extension.txt and local/processor.txt in OpenTelemetry Contrib repository based on components file. Example content of local/extension.txt:

      sumologicextension.NewFactory(),
ballastextension.NewFactory(),
zpagesextension.NewFactory(),
asapauthextension.NewFactory(),
awsproxy.NewFactory(),
basicauthextension.NewFactory(),
bearertokenauthextension.NewFactory(),
fluentbitextension.NewFactory(),
healthcheckextension.NewFactory(),
httpforwarderextension.NewFactory(),
jaegerremotesampling.NewFactory(),
oauth2clientauthextension.NewFactory(),
dockerobserver.NewFactory(),
ecsobserver.NewFactory(),
ecstaskobserver.NewFactory(),
hostobserver.NewFactory(),
k8sobserver.NewFactory(),
oidcauthextension.NewFactory(),
pprofextension.NewFactory(),
sigv4authextension.NewFactory(),
filestorage.NewFactory(),
dbstorage.NewFactory(),

    2. Run the following snippet in order to prepare markdown links for README.md:

      for kind in extension processor receiver exporter; do
  echo "#####${kind}#####"
  for component in $(cat local/${kind}.txt | sed "s/\..*//g"); do
    export dir=$(find ${kind} -name "${component}");
    NAME=$(grep -oRP '(?<=typeStr\s)(.*?)=(.*?)"(.*?)"' "${dir}" | grep -oP '\w+"$' | sed 's/"//g');
    echo "[${NAME}][${component}]";
  done 2>/dev/null
done

    3. Copy and fix the output

    4. Copy fixed output to spreadsheet. Every component in separate column as in README.md.

    5. Sort components and add placeholder to empty rows. Placeholders make it easier to format table as markdown in next steps.

    6. Copy table into text editor with support for regexp replacement.

    7. Prepare table in markdown format. We recommend to use regexp replacement.

    8. Prepare links for the table. You can use regexp replacement in order to generate it

    9. Carefully analyse git diff and fix unwanted changes.

Running Tracing E2E tests

We currently have some legacy E2E tests ported from our OT fork, which serve as a means of verifying feature parity for tracing as we migrate it to this distribution. The tests are run by CircleCI on demand for main and release branches, and are defined here.

In order to run the tests, go to the CircleCI page, choose the branch you want, and manually approve the workflow to run. Note that you need commiter rights in this repository to run the tests.

Approving the workflow in CircleCI

Updating journalctl

Journalctl is dependency for journaldreceiver. In order to update it, please update debian version in Dockerfile files. Please see available debian versions.

export DEBIAN_VERSION=11.3
make update-journalctl