wehub-resource-sync
131 lines
3.5 KiB
Markdown
131 lines
3.5 KiB
Markdown
# maintaining
|
|
|
|
This document is for LightGBM maintainers.
|
|
|
|
## Managing Dependencies
|
|
|
|
### Locked Environments with `pixi`
|
|
|
|
This project uses `pixi` for tasks and CI jobs that run with a locked set of dependencies.
|
|
|
|
In general, updating these environments looks like:
|
|
|
|
1. manually modify `pixi.toml`
|
|
2. run `pixi install`
|
|
|
|
And running inside one looks like:
|
|
|
|
```shell
|
|
# interactive shell
|
|
pixi shell -e py310
|
|
|
|
# run a task
|
|
pixi run -e py310 python -c "import pandas; print(pandas.__version__)"
|
|
```
|
|
|
|
See https://pixi.prefix.dev/latest/ for more details.
|
|
|
|
|
|
## Releasing
|
|
|
|
### Step 1: Put up a Release PR
|
|
|
|
Create a pull request into `main` which prepares the source code for release.
|
|
|
|
Copy the description and checklist from the previous release PR (for example: https://github.com/lightgbm-org/LightGBM/pull/6796).
|
|
|
|
This should usually also include a checklist of other issues and PRs that should be completed for the release,
|
|
and the PR should be used to discuss what makes it into the release.
|
|
|
|
### Step 2: Merge the Release PR
|
|
|
|
Once the PR is approved, merge it.
|
|
|
|
Do not merge any other PRs into `main` until the rest of the release is complete.
|
|
|
|
### Step 3: Wait for a New CI Run on `main`
|
|
|
|
Wait for all CI runs triggered by the merge to `main` to complete successfully.
|
|
|
|
These runs build and test the official artifacts that will be attached to the GitHub release and published to package managers.
|
|
|
|
### Step 4: Create a Release
|
|
|
|
Navigate to https://github.com/lightgbm-org/LightGBM/releases.
|
|
|
|
Click "edit" on the draft release that `release-drafter` has created there.
|
|
|
|
* update the tag and release title to match the version of LightGBM, in the format `v{major}.{minor}.{patch}`
|
|
* ensure that tag points at the commit on `main` created by merging the release PR
|
|
|
|
When you're satisfied with the state of the release, click "Publish release".
|
|
|
|
### Step 5: Upload Artifacts
|
|
|
|
After creating a release, run the following from the root of the repo to populate it with artifacts.
|
|
|
|
```shell
|
|
# download all artifacts to a local directory
|
|
./.ci/download-artifacts.sh ${COMMIT_ID}
|
|
|
|
# attach them to the GitHub release
|
|
gh release upload \
|
|
--repo lightgbm-org/LightGBM \
|
|
"${TAG}" \
|
|
./release-artifacts/*
|
|
```
|
|
|
|
Where:
|
|
|
|
* `COMMIT_ID` = full commit hash of the commit on `main` corresponding to the release
|
|
* `TAG` = the tag for the release (e.g. `v4.6.0`)
|
|
|
|
### Step 6: Complete All Other Post-merge Release Steps
|
|
|
|
These include things like publishing to package managers, updating build configs for repackagers like ``conda-forge``, and many other steps.
|
|
|
|
See the release checklist on the PR for details.
|
|
|
|
## Nightly Packages
|
|
|
|
Nightly packages for the `lightgbm` Python package are uploaded to https://anaconda.org/lightgbm-packages on every merge to `main`.
|
|
|
|
That's done using an upload token stored in a secret in CI.
|
|
Those tokens expire after 1 year.
|
|
|
|
To generate a new one, run the following.
|
|
|
|
```shell
|
|
# install Anaconda CLI
|
|
conda install -y -c conda-forge \
|
|
anaconda-auth \
|
|
anaconda-client
|
|
|
|
# authenticate locally
|
|
anaconda auth login
|
|
|
|
# create a token (this expires after 1 year)
|
|
TOKEN=$(
|
|
anaconda org auth \
|
|
--create \
|
|
--name nightly-uploads \
|
|
--org lightgbm-packages \
|
|
--scopes 'api:read api:write pypi:upload'
|
|
)
|
|
```
|
|
|
|
That token can be used by maintainers to manually upload packages as well.
|
|
|
|
For example:
|
|
|
|
```shell
|
|
./.ci/download-artifacts.sh $(git rev-parse HEAD)
|
|
|
|
# NOTE: set upload token in environment variable 'ANACONDA_API_TOKEN'
|
|
anaconda upload \
|
|
--package lightgbm \
|
|
--force-metadata-update \
|
|
-t pypi \
|
|
./release-artifacts/*.whl
|
|
```
|