2018-03-06 02:50:39 -07:00
# Local Development
2020-11-03 03:55:36 -07:00
This document gives tips and tricks on how to run Renovate locally to add features or fix bugs.
You can improve this documentation by opening a pull request.
For example, if you think anything is unclear, or you think something needs to be added, open a pull request!
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
## Installation
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
### Prerequisites
2019-08-23 00:54:17 -06:00
2020-11-03 03:55:36 -07:00
You need the following dependencies for local development:
2019-08-23 00:54:17 -06:00
2024-06-07 03:08:26 -06:00
- Git `>=2.45.1`
2024-07-22 04:05:39 -06:00
- Node.js `^20.15.1`
2024-06-07 03:08:26 -06:00
- pnpm `^9.0.0` (use corepack)
2020-10-23 09:42:57 -06:00
- C++ compiler
2019-10-04 01:17:47 -06:00
2024-10-21 23:36:20 -06:00
We recommend you use the version of Node.js defined in the repository's `.nvmrc` or use [Volta ](https://volta.sh/ ) to manage your tool versions.
Volta will apply automatically the correct version of Node.js and pnpm when you enter the repository directory.
2020-02-13 13:53:27 -07:00
2021-03-09 15:21:38 -07:00
#### Linux
2019-08-23 00:54:17 -06:00
2020-11-03 03:55:36 -07:00
You can use the following commands on Ubuntu.
2019-08-23 00:54:17 -06:00
```sh
2024-03-17 04:56:59 -06:00
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
2019-08-23 00:54:17 -06:00
sudo apt-get update
2023-08-03 05:54:54 -06:00
sudo apt-get install -y git build-essential nodejs
corepack enable
2019-08-23 00:54:17 -06:00
```
2023-06-16 01:46:08 -06:00
#### Nix
2023-08-03 13:43:47 -06:00
To enter a development shell with the necessary packages, run `nix-shell --packages gcc gitFull nodejs` and then `corepack enable` .
2023-06-16 01:46:08 -06:00
2021-03-09 15:21:38 -07:00
#### Windows
2019-08-23 00:54:17 -06:00
2020-11-03 03:55:36 -07:00
Follow these steps to set up your development environment on Windows 10.
2022-03-16 07:51:27 -06:00
If you already installed a part, skip the corresponding step.
2019-08-23 00:54:17 -06:00
2020-11-06 04:00:57 -07:00
- Install [Git ](https://git-scm.com/downloads ). Make sure you've [configured your username and email ](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup )
- Install [Node.js LTS ](https://nodejs.org/en/download/ )
2021-11-17 07:17:29 -07:00
- In an Administrator PowerShell prompt, run `npm install -global npm` and then `npm --debug install --global windows-build-tools`
2024-06-07 03:08:26 -06:00
- Enable corepack with: `corepack enable`
2019-08-23 00:54:17 -06:00
2021-02-27 23:06:00 -07:00
You can see what versions you're using like this:
2018-03-06 02:50:39 -07:00
2021-02-27 23:06:00 -07:00
```powershell
2019-10-04 01:17:47 -06:00
PS C:\Windows\system32> git --version
PS C:\Windows\system32> node --version
2023-08-03 13:43:47 -06:00
PS C:\Windows\system32> pnpm --version
2019-10-04 01:17:47 -06:00
```
2018-03-06 02:50:39 -07:00
2023-04-17 08:19:14 -06:00
#### VS Code Dev Containers
2020-03-23 04:48:25 -06:00
2023-04-17 08:19:14 -06:00
If you are using [VS Code ](https://code.visualstudio.com/ ) you can skip installing [the prerequisites ](#prerequisites ) and work in a [development container ](https://code.visualstudio.com/docs/devcontainers/containers ) instead.
2020-03-23 04:48:25 -06:00
2023-01-24 02:08:08 -07:00
- Install the [Dev Containers extension ](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers ) and [check its system requirements ](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers#system-requirements )
2020-03-23 04:48:25 -06:00
- Open the repository folder in VS Code
2020-11-06 04:00:57 -07:00
- Choose "Reopen in Container" via the command palette or the small button in the lower left corner
2020-03-23 04:48:25 -06:00
2023-08-22 06:07:21 -06:00
The VS Code [integrated terminal ](https://code.visualstudio.com/docs/editor/integrated-terminal ) is now running in the container and can be used to run more commands.
2020-03-23 04:48:25 -06:00
2023-04-17 08:19:14 -06:00
To build inside the container:
```shell
2023-08-03 13:43:47 -06:00
pnpm build
2023-04-17 08:19:14 -06:00
```
2022-04-13 02:16:07 -06:00
#### Local Docker
If, for some reason, you can't run the relevant versions on your local machine, you can run everything from a Docker image.
2024-06-07 03:08:26 -06:00
To build the correct Docker image:
2022-04-13 02:16:07 -06:00
```
docker build -f .devcontainer/Dockerfile -t renovatebot_local .
```
2024-06-07 03:08:26 -06:00
Starting from Docker Engine `23.0` and Docker Desktop `4.19` , Docker uses Buildx by default.
2023-10-25 04:28:49 -06:00
So you must run the following command to get the image loaded to the Docker image store:
```
docker build -f .devcontainer/Dockerfile -t renovatebot_local --load .
```
2023-08-03 13:43:47 -06:00
Then you can run `pnpm` directly from Docker, for instance:
2022-04-13 02:16:07 -06:00
```
2023-10-25 04:28:49 -06:00
docker run -it --rm -v "${PWD}:/usr/src/app" -w /usr/src/app renovatebot_local pnpm install
2022-04-13 02:16:07 -06:00
```
2020-11-03 03:55:36 -07:00
## Fork and Clone
2018-03-06 02:50:39 -07:00
2021-05-25 21:04:37 -06:00
If you want to contribute to the project, you should first "fork" the main project using the GitHub website and then clone your fork locally.
2023-08-03 13:43:47 -06:00
The Renovate project uses the [pnpm ](https://github.com/pnpm/pnpm ) package management system instead of npm.
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
To ensure everything is working properly on your end, you must:
2018-03-06 02:50:39 -07:00
2023-08-03 13:43:47 -06:00
1. Install all dependencies with `pnpm install`
1. Make a build with `pnpm build` , which should pass with no errors
1. Verify all tests pass and have 100% test coverage, by running `pnpm test`
1. Verify the installation by running `pnpm start` . You must see this error: `You must configure a GitHub personal access token`
2018-03-06 02:50:39 -07:00
2022-12-08 03:29:16 -07:00
Do not worry about the token error for now, as you will be given instructions on how to configure the token a little later down in this document.
2021-11-10 03:57:41 -07:00
You only need to do these steps once.
2019-10-04 01:17:47 -06:00
2020-11-03 03:55:36 -07:00
Before you submit a pull request you should:
2019-10-04 01:17:47 -06:00
2023-08-03 13:43:47 -06:00
1. Install newer dependencies with `pnpm install`
1. Run the tests with `pnpm test`
2018-03-06 02:50:39 -07:00
## Platform Account Setup
2020-11-03 03:55:36 -07:00
Although it's possible to make small source code improvements without testing against a real repository, in most cases you should run a "real" test on a repository before you submit a feature or fix.
2020-11-02 01:52:37 -07:00
It's possible to do this against GitHub, GitLab or Bitbucket public servers.
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
### Register new account (optional)
2018-03-06 02:50:39 -07:00
2024-06-07 03:08:26 -06:00
If you're going to be doing a lot of Renovate development then we recommend that you set up a dedicated test account on GitHub or GitLab, so that you reduce the risk that you accidentally cause problems when testing out Renovate.
2018-09-17 04:13:42 -06:00
2018-03-06 02:50:39 -07:00
e.g. if your GitHub username is "alex88" then maybe you register "alex88-testing" for use with Renovate.
2020-11-03 03:55:36 -07:00
### Generate platform token
2018-03-06 02:50:39 -07:00
2020-11-02 01:52:37 -07:00
Once you have decided on your platform and account, log in and [generate a "Personal Access Token" ](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ ) that can be used to authenticate Renovate.
2024-06-07 03:08:26 -06:00
Select the **repo** scope when generating the token.
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
### Export platform token
2018-03-06 02:50:39 -07:00
2018-12-04 05:49:38 -07:00
Although you can specify a token to Renovate using `--token=` , it can be inconvenient if you need to include this every time.
2019-01-13 23:53:42 -07:00
You are better off to instead export the Environment Variable `RENOVATE_TOKEN` for this.
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
### Run against a real repo
2018-12-04 05:49:38 -07:00
2024-06-07 03:08:26 -06:00
To make sure everything is working, create a test repository in your account, e.g. like `https://github.com/r4harry/testrepo1` .
Now, add a file called `.nvmrc` with the content `20.0.0` .
2023-08-03 13:43:47 -06:00
Now run against the test repo you created, e.g. `pnpm start r4harry/testrepo1` .
2021-02-27 23:06:00 -07:00
If your token is set up correctly, you should find that Renovate created a "Configure Renovate" PR in the `testrepo1` .
2018-12-04 05:49:38 -07:00
If this is working then in future you can create other test repos to verify your code changes against.
2018-03-06 02:50:39 -07:00
## Tests
2023-08-03 13:43:47 -06:00
You can run `pnpm test` locally to test your code.
2020-11-03 03:55:36 -07:00
We test all PRs using the same tests, run on GitHub Actions.
2023-08-03 13:43:47 -06:00
`pnpm test` runs an `eslint` check, a `prettier` check, a `type` check and then all the unit tests using `jest` .
2018-03-16 09:02:11 -06:00
2022-01-03 03:25:50 -07:00
Refactor PRs should ideally not change or remove tests (adding tests is OK).
2020-11-03 03:55:36 -07:00
### Jest
2023-08-03 13:43:47 -06:00
Run the Jest unit tests with the `pnpm jest` command.
You can also run a subset of the Jest tests using file matching, e.g. `pnpm jest composer` or `pnpm jest workers/repository/update/branch` .
2020-11-03 03:55:36 -07:00
If you get a test failure due to a "snapshot" mismatch, and you are sure that you need to update the snapshot, then you can append `-u` to the end.
2023-08-03 13:43:47 -06:00
e.g. `pnpm jest composer -u` would update the saved snapshots for _all_ tests in `**/composer/**` .
2019-02-28 02:35:21 -07:00
2020-11-03 03:55:36 -07:00
### Coverage
2018-03-06 02:50:39 -07:00
2022-03-16 07:50:20 -06:00
The Renovate project maintains 100% test coverage, so any Pull Request will fail if it does not have full coverage for code.
2023-08-22 06:07:21 -06:00
Using `// istanbul ignore` is not ideal, but can be a pragmatic solution if adding more tests wouldn't really prove anything.
2018-03-06 02:50:39 -07:00
2020-06-25 22:36:35 -06:00
To view the current test coverage locally, open up `coverage/index.html` in your browser.
2018-03-06 02:50:39 -07:00
2020-11-02 01:52:37 -07:00
Do not let coverage put you off submitting a PR!
Maybe we can help, or at least guide.
2018-03-06 02:50:39 -07:00
Also, it can be good to submit your PR as a work in progress (WIP) without tests first so that you can get a thumbs up from others about the changes, and write tests after.
2020-11-03 03:55:36 -07:00
## Linting and formatting
2018-03-06 02:50:39 -07:00
2021-02-27 23:06:00 -07:00
We use [Prettier ](https://github.com/prettier/prettier ) to format our code.
2023-08-03 13:43:47 -06:00
If your code fails `pnpm test` due to a `prettier` rule then run `pnpm lint-fix` to fix it or most `eslint` errors automatically before running `pnpm test` again.
2021-02-27 23:06:00 -07:00
You usually don't need to fix any Prettier errors by hand.
2018-03-06 02:50:39 -07:00
2023-08-03 13:43:47 -06:00
If you're only working on the documentation files, you can use the `pnpm doc-fix` command to format your work.
2021-08-04 04:56:27 -06:00
2024-08-14 11:44:52 -06:00
## Documentation
We use [MkDocs ](https://www.mkdocs.org ) to generate the documentation.
You can run `pnpm build:docs` to generate the docs.
Then use `pnpm mkdocs serve` to preview the documentation locally.
The docs will update automatically when you run `pnpm build:docs` again, no need to stop the `pnpm mkdocs serve` command.
2018-12-13 13:11:44 -07:00
## Keeping your Renovate fork up to date
2021-04-22 08:32:12 -06:00
First of all, never commit to the `main` branch of your fork - always use a "feature" branch like `feat/1234-add-yarn-parsing` .
2018-12-13 13:11:44 -07:00
2022-07-29 22:27:23 -06:00
Make sure your fork is up-to-date with the Renovate `main` branch, check this each time before you create a new branch.
2021-02-27 23:06:00 -07:00
To do this, see these GitHub guides:
2018-12-13 13:11:44 -07:00
2024-06-07 03:08:26 -06:00
- [Configuring a remote for a fork ](https://help.github.com/articles/configuring-a-remote-for-a-fork/ )
- [Syncing a fork ](https://help.github.com/articles/syncing-a-fork/ )
2018-12-13 13:11:44 -07:00
2018-03-06 02:50:39 -07:00
## Tips and tricks
2020-11-03 03:55:36 -07:00
### Log files
2018-03-06 02:50:39 -07:00
2024-06-07 03:08:26 -06:00
Usually the `debug` log level is good enough to troubleshoot most problems or verify functionality.
2018-03-06 02:50:39 -07:00
2020-11-12 23:06:53 -07:00
It's usually easier to have the logs in a file that you can open with a text editor.
You can use a command like this to put the log messages in a file:
2018-03-06 02:50:39 -07:00
2023-08-03 13:43:47 -06:00
```sh
LOG_LEVEL=debug pnpm start myaccount/therepo > debug.log
2018-03-06 02:50:39 -07:00
```
2024-06-07 03:08:26 -06:00
The example command will redirect and save Renovate's output to the `debug.log` file.
Warning: the command will overwrite a existing `debug.log` !
2018-03-06 02:50:39 -07:00
2020-11-03 03:55:36 -07:00
### Adding configuration options
2018-03-06 02:50:39 -07:00
2021-02-27 23:06:00 -07:00
We want stay backwards-compatible as much as possible, as well as make the code configurable.
So most new functionality should be controllable via configuration options.
2018-03-06 02:50:39 -07:00
2021-08-14 23:25:30 -06:00
Create your new configuration option in the `lib/config/options/index.ts` file.
2022-08-14 09:16:48 -06:00
Also create documentation for the option in the `docs/usage/configuration-options.md` file.
2018-09-17 04:13:42 -06:00
## Debugging
2021-02-27 23:06:00 -07:00
### Chrome's inspect tool
2023-05-29 02:20:40 -06:00
You can debug Renovate with Chrome's inspect tool.
2021-02-27 23:06:00 -07:00
Here's an example:
2018-09-17 04:13:42 -06:00
2022-11-30 02:37:00 -07:00
1. Open `chrome://inspect` in Chrome, then select "Open dedicated DevTools for Node"
2021-02-27 23:06:00 -07:00
1. Add a `debugger;` statement somewhere in the source code where you want to start debugging
2023-08-03 13:43:47 -06:00
1. Run Renovate using `pnpm debug ...` instead of `pnpm start ...`
2022-11-30 02:37:00 -07:00
1. Select "Resume script execution" in Chrome DevTools and wait for your break point to be triggered
2021-02-27 23:06:00 -07:00
### VS Code
2019-06-29 22:29:17 -06:00
2023-05-29 02:20:40 -06:00
You can also debug Renovate with VS Code.
2021-02-27 23:06:00 -07:00
Here's an example:
2019-06-29 22:29:17 -06:00
2021-02-27 23:06:00 -07:00
1. In the configuration file, e.g. `config.js` in the root directory of the project, add `token` with your Personal Access Token
2019-06-29 22:29:17 -06:00
2. In the same configuration file, add `repositories` with the repository you want to test against. The file `config.js` would look something like this:
```javascript
module.exports = {
token: 'xxxxxxxx',
repositories: ['r4harry/testrepo1'],
};
```
2021-03-09 15:21:38 -07:00
<!-- markdownlint - disable MD029 -->
2020-11-06 04:00:57 -07:00
3. Set a breakpoint somewhere in the source code and launch the application in debug mode with selected configuration as `debug`
4. Wait for your breakpoint to be triggered