From 7a074e837884b0fc3f1006d56e387bd7ce33fb5d Mon Sep 17 00:00:00 2001 From: Evan Maddock <5157277+EbonJaeger@users.noreply.github.com> Date: Sat, 2 Dec 2023 11:06:52 -0500 Subject: [PATCH] packaging: Try to clarify some sections in the packaging steps (#438) Ref https://github.com/getsolus/help-center-docs/issues/437 Signed-off-by: Evan Maddock --- docs/packaging/creating-a-new-package.md | 34 ++++++++----- .../packaging/updating-an-existing-package.md | 50 +++++++++++++++---- 2 files changed, 62 insertions(+), 22 deletions(-) diff --git a/docs/packaging/creating-a-new-package.md b/docs/packaging/creating-a-new-package.md index 6a20f7908..f5b4fc04a 100644 --- a/docs/packaging/creating-a-new-package.md +++ b/docs/packaging/creating-a-new-package.md @@ -30,18 +30,11 @@ git switch main git pull ``` -## Create a New Package Directory +## Create a New Branch -Create a new subdirectory for the new package. Use the package name as the directory name and create it in the appropriate prefix directory in `packages` (usually the first letter of the package). +It's always a good idea to switch to a new git branch before beginning packaging work. This helps to separate your work from any new changes made to the package repository, which will allow you to more easily rebase any changes if needed. To do so run: ```bash -mkdir packages/t/tree -cd packages/t/tree -``` - -Now, create a new branch. 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. To do so run: - -``` git switch -c your-branch ``` @@ -53,7 +46,7 @@ You must add a file called `MAINTAINERS.md` using the template in [Maintainershi You will need a link to the most recent source tarball for this from the software's website. -To create a skeleton `package.yml` file, use the the `go-task new` command. +To create a skeleton `package.yml` file, use the `go-task new` command. This command takes two arguments, in the following order: @@ -133,7 +126,12 @@ Understanding how to translate source code into a good `package.yml` file is the ## Build the Package -Build the package with `go-task`. +Build the package using `go-task`. The default task will build the package against the Unstable repository, so you don't have to specify a task here. + +```bash +go-task +``` + Once the build completes, your directory should now include the following files: ```text @@ -150,11 +148,21 @@ Once your package has built successfully, you will need to [test it](testing-a-p ## Commit your Changes -Check the [changes in your files](git-basics). +Check the [changes in your files](git-basics#check-the-changes-in-your-files). [Add / remove files as necessary to the commit](git-basics.md). 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`. +Double-check that everything looks correct and all of the files have been staged before committing. + +```bash +git status +``` + +If all looks well, commit your changes. + +```bash +git commit +``` ### Commit message format for new packages diff --git a/docs/packaging/updating-an-existing-package.md b/docs/packaging/updating-an-existing-package.md index c423d7196..a1deca0ea 100644 --- a/docs/packaging/updating-an-existing-package.md +++ b/docs/packaging/updating-an-existing-package.md @@ -33,24 +33,41 @@ 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: +It's always a good idea to switch to a new git branch before beginning packaging work. This helps to separate your work from any new changes made to the package repository, which will allow you to more easily rebase any changes if needed. To do so run: ```bash git switch -c update_nano ``` -## Bumping a Package +## Updating a Package + +There are two types of package updates: a package bump, and moving a package to a different version. 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. +### Bumping a Package -## Updating a Package +Bumping can be achieved by running the `bump` task, which increments the release number by 1. + +```bash +go-task bump +``` + +Check to make sure that the result is as expected. + +```bash +git diff package.yml +``` + +:::note +Certain packages with long descriptions might have their description messed up when this is run. Check if this happened, and fix it if necessary. +::: + +### Using a Different Version -To update the package to a newer version, use the `go-task update` command. +To update the package to a newer version, use the `update` task. -This command takes two arguments, in the following order: +This task takes two arguments, in the following order: 1. Version 2. Source URL @@ -69,7 +86,12 @@ There must be a file called `MAINTAINERS.md` using the template in [Maintainersh ## Build the package -After bumping or updating the package, build it by running `go-task`. +Build the package using `go-task`. The default task will build the package against the Unstable repository, so you don't have to specify a task here. + +```bash +go-task +``` + Once your package has built successfully, you will need to [test it](testing-a-package). ## Commit Your Changes @@ -78,7 +100,17 @@ Check the [changes in your files](git-basics#check-the-changes-in-your-files). [Add / remove files as necessary to the commit](git-basics.md). 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`. +Double-check that everything looks correct and all of the files have been staged before committing. + +```bash +git status +``` + +If all looks well, commit your changes. + +```bash +git commit +``` ### Commit message format for updated / bumped packages