Updating an Existing Package
This article will go over updating a package that is already in the Solus package repositories.
Please look to see if an issue has been filed for the software update. If there is an existing request, please add a link to it in your pull request. Ex:
This PR resolves software update request https://github.com/getsolus/packages/issues/123
Fork the getsolus/packages Repository / Update Your Fork
Create a Fork
If you had not yet done so already, fork getsolus/packages using the GitHub web UI or gh
cli tool from the github-cli
package. It will be forked to github.com/yourgithubaccount/packages
.
Update a Fork
If you already have a fork of getsolus/packages in GitHub, log into GitHub. Make sure you're looking at the main
branch. Check to see that your fork is up to date with the main repo it was forked from. If your fork indicates it is behind, use the "Sync fork" button to bring it up to date.
Clone the package repo / update your clone
Clone the repo
If you do not yet have a clone of your packages repo fork, change to your packaging directory and clone your fork. Then, switch to the directory of the package to update. For example:
cd ~/solus-builds
gh repo clone yourgithubaccount/packages
cd packages/packages/n/nano
Update an existing clone
If you already have a local clone, you need to bring it up to date. To do so run:
cd ~/solus-builds/packages/n/nano
git switch main
git pull
Switch to a New Git Branch
It's always a good idea to switch to a new git branch before beginning packaging work. This will allow you to more easily separate your work from any new changes made to the package repository, which will allow you to more easily rebase any changes if needed. Example:
git switch -c update_nano
Bumping a Package
Bumping a package is typically done when rebuilding against a changed dependency, such as imagemagick
needing to be rebuilt if libwebp
changes. It is also done if changes are being made to the package, such as adding new dependencies or other modifications which aren't a version update.
This can be achieved by doing go-task bump
, which increments the release number by 1.
Updating a Package
To update the package to a newer version, use the yupdate
tool. This is located at /usr/share/ypkg/yupdate.py
. We recommend setting an alias via your .bashrc
, .zshrc
, or method appropropriate to your shell.
alias updatePackage='/usr/share/ypkg/yupdate.py'
This script takes two arguments, in the following order:
- Version
- Source URL
If you're updating the package to a newer version, naturally you would change both the version and source. If you're merely changing the source URL for the existing version, just pass the same version number and the new source URL.
Example:
/usr/share/ypkg/yupdate.py 1.0 https://example.com/example-1.0.tar.xz
The MAINTAINERS.md
File
There must be a file called MAINTAINERS.md
using the template in Maintainership. Add it if it does not already exist. It should name the current maintainer(s) of the package.
Build the package
After bumping or updating the package, build it by running go-task
.
Once your package has built successfully, you will need to test it.
Commit Your Changes
Check the changes in your files.
Add / remove files as necessary to the commit. Then, check your branch.
Run git status
. Make sure all the files you changed are staged, and that there are no untracked files. When all is well, run git commit --cleanup=scissors
.
The --cleanup=scissors
flag is necessary. By default, git treats lines starting with # as a comment, and removes them.
If you would like to always use this flag without having to type it manually you can do so in one of two ways.
Set an alias in
~/.gitconfig
such ascs = commit --cleanup=scissors
You can then use
git cs
which will do the same thing asgit commit --cleanup=scissors
.Set your git global config to always use the flag. To do so run
git config --global commit.cleanup scissors
Commit message format for updated / bumped packages
There should be a meaningful summary line (which starts with the package name), a blank line, and then the rest of the commit message.
- Bullet point lists should start with a dash.
- Include a changelog with a brief list of updates from the upstream release notes, with no links.
- There may also be a section for Solus specific work (e.g. rebuild against x / rework to remove dependency).
- Optional: A link to the upstream release notes page.
- Include your Test Plan.
Here is an example in our standard format (make sure to check the box in the checklist):
foo: Update to 1.2.3
## Summary
Bugfixes:
- Fixed a crash
- Something else
Enhancements:
- Implemented a feature
- Error when encountering a thing
**Full release notes:**
- [1.2.3](https://github.com/foo/foo/releases/tag/v1.2.3)
## Test Plan
- Launched the application
- Exercised the UI
- Exercised some feature
## Checklist
- [] Package was built and tested against unstable
For more information on suitable commit messages, please check the tooling central documentation.
- If you want to link this pull request to an existing issue, simply mention it in your commit message (use the full URL):
The inclusion of <somepackage> fixes https://github.com/getsolus/packages/issues/123
- If you need a change to depend on another change, mention it in the commit message too (use the full URL):
Depends on https://github.com/getsolus/packages/issues/234
Next, you'll submit a pull request for review.