mirror of https://github.com/renovatebot/renovate
110 lines
6.1 KiB
Markdown
110 lines
6.1 KiB
Markdown
---
|
|
title: Renovate and changelogs
|
|
description: Learn how Renovate fetches changelogs
|
|
---
|
|
|
|
This page explains how Renovate fetches changelogs, when it can display them, and more.
|
|
|
|
## How Renovate detects changelogs
|
|
|
|
Renovate detects and populates changelogs by:
|
|
|
|
1. Identifying a source URL from the datasource response for a package, and saving that internally as `sourceUrl` if found
|
|
1. Checking if Renovate's internal [_sourceUrl_ data](https://github.com/renovatebot/renovate/blob/main/lib/data/source-urls.json) for the package includes a source URL
|
|
1. Looking up the source URL, if it resides on a supported platform (e.g. GitHub)
|
|
1. Checking for both "Releases" metadata in the repository and any commonly known "changelog" file names
|
|
1. Filtering the found releases to only include those versions being updated by the current PR
|
|
1. Formatting and embedding the results into the PR body
|
|
|
|
## Changelogs for private packages
|
|
|
|
For private packages, the algorithm is mostly the same as described above, with the additional considerations:
|
|
|
|
- Renovate must be able to access the private package in the first place
|
|
- The private registry must include the source URL in its response
|
|
- Renovate must be able to detect and authenticate with whatever private repository corresponds to the source URL
|
|
|
|
For more details, see [Private packages, looking up changelogs](../getting-started/private-packages.md#looking-up-changelogs).
|
|
|
|
## Relevant configuration options
|
|
|
|
### [`fetchChangelogs`](../configuration-options.md#fetchchangelogs)
|
|
|
|
Set to `off` if changelog fetching is causing a problem.
|
|
|
|
Set to `branch` if you have an advanced use case where you're embedding changelogs in the Git commit itself, we don't recommend this due to its potential size.
|
|
|
|
### [`changelogUrl`](../configuration-options.md#changelogurl)
|
|
|
|
This doesn't help with _fetching_ the changelogs, but if you configure it then Renovate will include a link to this URL in the PR body, so users can click through to read the changelog.
|
|
|
|
## Platforms that Renovate can fetch changelogs from
|
|
|
|
See the list of platforms in the [`fetchChangelogs` config option docs](../configuration-options.md#fetchchangelogs).
|
|
|
|
### Running Renovate on a non-GitHub platform
|
|
|
|
Most Open Source packages are hosted on github.com, which means most changelogs are hosted there too.
|
|
Fetching changelogs from github.com requires a GitHub token because GitHub blocks unauthenticated GraphQL API use.
|
|
|
|
This means that if you run Renovate on self-hosted GitHub Enterprise Server, or any non-GitHub platform which Renovate supports, then you need to configure a github.com Personal Access Token in Renovate in order to fetch changelogs.
|
|
|
|
Read [Running Renovate, GitHub.com token for changelogs](../getting-started/running.md#githubcom-token-for-changelogs) to learn more.
|
|
|
|
## Troubleshooting missing changelogs
|
|
|
|
Follow these steps to find out why Renovate does not find a changelog:
|
|
|
|
1. The datasource for this package does not support sourceUrls.
|
|
- If the registry fundamentally does not provide this data, then the only possibility is for it to be manually populated through PRs to Renovate's source code
|
|
- If the registry provides source URLs in its response but Renovate does not understand the required fields, then raise a feature request with examples, or better yet a Pull Request to implement support for the source URL parsing/mapping yourself
|
|
- Sometimes self-hosted versions of registries don't include the full metadata compared to what the public registries do
|
|
1. The package was published without source URL information being included.
|
|
- For example, occasionally `npm` packages don't have `repository` fields included
|
|
- For example, Docker images regularly do not have the required `LABEL` entry
|
|
1. Renovate cannot access the source repository
|
|
- This is typically a concern for private repositories only
|
|
- Check if the token Renovate uses has access rights to the repository you need it to access
|
|
1. Renovate cannot detect the file names or release name convention within the repository
|
|
- In this case an enhancement to Renovate might be needed to better detect the releases/formats, assuming the package/repository has a reasonable convention to follow
|
|
|
|
If none of this helps, search the Renovate issues and discussions to see if this is a known problem.
|
|
|
|
## Advice for package maintainers
|
|
|
|
This section is for package maintainers that want to make sure Renovate can see their changelogs.
|
|
|
|
There isn't much information to add other than what's already written above.
|
|
|
|
Make sure that you have the required source URL in your package metadata, not just in your repository but also in the final data which the registry returns.
|
|
For example, we have seen cases where the `repository` field in npm's `package.json` is populated correctly in the repository, but stripped out as part of the publishing process.
|
|
|
|
### Let Renovate understand your versioning and changelogs
|
|
|
|
In general, Renovate can understand your versions and changelogs best when you:
|
|
|
|
- Use SemVer versioning, so `major.minor.patch`
|
|
- Use the [`semantic-release` bot](https://github.com/semantic-release/semantic-release) to automate the release process
|
|
|
|
Try to avoid things like:
|
|
|
|
- Stripping out the trailing `.0` unnecessarily (e.g. having a package `3.1.0` on a registry but using only `3.1` in your changelogs)
|
|
- Using "Release names" in a way which makes the actual version hard to discern (e.g. instead of `3.0.0` you title your release notes `Big news! v3 is here`
|
|
|
|
### npm package maintainers
|
|
|
|
As maintainer, make sure the `package.json` has a filled in `repository` field, read the [npm Docs, configuring npm `repository` field](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#repository) to learn more.
|
|
If your repository uses the monorepo pattern make sure _each_ `package.json` file has a `repository` field.
|
|
|
|
### maven package maintainers
|
|
|
|
Read [`maven` datasource, making your changelogs fetchable](../modules/datasource/maven/index.md#making-your-changelogs-fetchable).
|
|
|
|
### Docker image maintainers
|
|
|
|
Read the [Docker datasource](../modules/datasource/docker/index.md) docs.
|
|
|
|
### Nuget package maintainers
|
|
|
|
See [Renovate issue #14128 about using NuGet's changelogs](https://github.com/renovatebot/renovate/issues/14128).
|