From b7a7d1314fb5ed8f916a6743f67134a8536986a2 Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Wed, 20 Sep 2023 01:56:29 +0200 Subject: [PATCH] Monorepo docs (#375) * Update packaging docs for the monorepo * Replace `make` with `go-task` * Remove `system.devel` from packaging requirements * Fix missing space --- docs/packaging/creating-a-new-package.md | 21 ++++---- docs/packaging/git-basics.md | 12 ++--- docs/packaging/prepare-for-packaging.mdx | 49 +++---------------- .../packaging/updating-an-existing-package.md | 23 ++++----- docs/packaging/your-first-package-update.md | 11 ++--- 5 files changed, 38 insertions(+), 78 deletions(-) diff --git a/docs/packaging/creating-a-new-package.md b/docs/packaging/creating-a-new-package.md index 686fcaca9..392c1fd7c 100644 --- a/docs/packaging/creating-a-new-package.md +++ b/docs/packaging/creating-a-new-package.md @@ -26,7 +26,7 @@ If you had not yet done so already, fork the repo [getsolus/packages](https://gi ### Update a Fork -If you already have a fork of [getsolus/packages](https://github.com/getsolus/packages) in GitHub, log into GitHub. Make sure you're looking at the master 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. +If you already have a fork of [getsolus/packages](https://github.com/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 packages repo / update your clone @@ -46,26 +46,23 @@ If you already have a local clone, you need to bring it up to date. To do this r ```bash cd ~/solus-builds/packages -git switch master +git switch main git pull ``` ## Create a New Package Directory -Create a new subdirectory for the new package. Use the package name as the directory name. 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: +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). ```bash -mkdir tree -cd tree -git switch -c your-branch +mkdir packages/t/tree +cd packages/t/tree ``` -## Link to the `Makefile` - -Every package directory needs a `Makefile`. To create it with the proper contents, run this: +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: -```bash -echo "include ../Makefile.common" > Makefile +``` +git switch -c your-branch ``` ## Create The `MAINTAINERS.md` File @@ -153,7 +150,7 @@ Understanding how to translate source code into a good `package.yml` file is the ## Build the Package -Build the package with `make` +Build the package with `go-task` Once the build completes, your directory should now include the following files: ```text diff --git a/docs/packaging/git-basics.md b/docs/packaging/git-basics.md index 4800f3952..27e830b26 100644 --- a/docs/packaging/git-basics.md +++ b/docs/packaging/git-basics.md @@ -10,12 +10,12 @@ summary: Basic git commands for packaging The recommended way to switch branches is `git switch`. To create a new branch use `git switch -c`. -## Keeping your branch up to date with the master branch +## Keeping your branch up to date with the main branch If there any new changes to the repository whilst you are still working on your branch you need to [sync your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork). -Run `git fetch`, and `git rebase origin/master` to pull the changes in. +Run `git fetch`, and `git rebase origin/main` to pull the changes in. You will need to fix any conflicts manually. -You can check your branch against master with `git diff origin/master..my-branch`. +You can check your branch against main with `git diff origin/main..my-branch`. ## Adding files @@ -47,11 +47,11 @@ Now that you've tested and reviewed your change, when you're happy with it, it's ## Deleting your branch after a pull request is merged Once your pull request has been accepted you can delete your working branches. -First, change to the package directory, switch to the master branch, then delete your local and the remote branches. +First, change to the package directory, switch to the main branch, then delete your local and the remote branches. ```bash cd ~/solus-builds/package -git switch master +git switch main git branch -D my-branch git push -d origin my-branch -``` \ No newline at end of file +``` diff --git a/docs/packaging/prepare-for-packaging.mdx b/docs/packaging/prepare-for-packaging.mdx index 079586949..febb16abd 100644 --- a/docs/packaging/prepare-for-packaging.mdx +++ b/docs/packaging/prepare-for-packaging.mdx @@ -34,32 +34,22 @@ Matrix=@username.matrix.org ## Installing Development Tools -We need to install a few things in order to get started with packaging. -The main packages we need are provided by the `system.devel` component. - -Namely: - -- `ypkg` the program that actually builds packages -- `make` used by our build tools for scripting - -```bash -sudo eopkg it -c system.devel -``` - -Additionally, we need a few more tools to carry out the packaging process: +We need to install a few things in order to get started with packaging: +- `go-task` is used by our build tools for scripting - `git` is used for version control of the solus sources - `github-cli` is used to make working with GitHub easier - `solbuild` is a lightweight container environment for building packages repeatably - `solbuild-config-unstable` sets up solbuild for working with the `unstable` repository +- `ypkg` is the program that actually builds packages ```bash -sudo eopkg it git github-cli solbuild solbuild-config-unstable +sudo eopkg it go-task git github-cli solbuild solbuild-config-unstable ypkg ``` ## Setting up a GitHub account -The Solus source repositories for the package repository currently reside on [github.com/solus-packages](https://github.com/solus-packages). You will need a GitHub account to submit patches and file issues. You can create a GitHub account [here](https://github.com/signup). Note that you will also need to set up [2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa)(two factor authentication) for your account. +The Solus source repositories for the package repository currently reside on [github.com/getsolus/packages](https://github.com/getsolus/packages). You will need a GitHub account to submit patches and file issues. You can create a GitHub account [here](https://github.com/signup). Note that you will also need to set up [2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa) (two factor authentication) for your account. ### Configure `github-cli`. @@ -98,33 +88,6 @@ mkdir ~/solus-builds cd solus-builds ``` -Next you need to set up `common`. This is a repository with a set of make scripts which enable you to more easily manage, build, check, and publish packages. - -Change into the directory you will keep the folders for the packages you will be building and clone the common repository with git. For instance if you have a package directory `/home/user/solus-builds` you would run: - -```bash -git clone https://github.com/getsolus/common.git -``` - -Next you need to set up a few symlinks. Do this from the same directory you executed the `git` command: - -```bash -ln -sv common/Makefile.common . -ln -sv common/Makefile.toplevel Makefile -ln -sv common/Makefile.iso . -``` - -Your packaging folder should look something similar to this: - -``` -└── solus-builds - ├── common - │ ├── *lots of stuff, not shown here* - ├── Makefile -> common/Makefile.toplevel - ├── Makefile.common -> common/Makefile.common - └── Makefile.iso -> common/Makefile.iso -``` - ## Recommended aliases Consider creating these aliases in your `.bashrc` file (or equivalent for the zsh or fish shell). @@ -149,4 +112,4 @@ alias updatePackage='/usr/share/ypkg/yupdate.py' ## Building Packages Your system is now set up for package work. -If you are new to packaging, see [Your First Package Update](your-first-package-update.md). \ No newline at end of file +If you are new to packaging, see [Your First Package Update](your-first-package-update.md). diff --git a/docs/packaging/updating-an-existing-package.md b/docs/packaging/updating-an-existing-package.md index 6dd549e9f..a82315222 100644 --- a/docs/packaging/updating-an-existing-package.md +++ b/docs/packaging/updating-an-existing-package.md @@ -19,26 +19,27 @@ This PR resolves software update request https://github.com/getsolus/packages/is ::: -## Fork the Package Repository / Update Your Fork + +## Fork the getsolus/packages Repository / Update Your Fork ### Create a Fork -If you had not yet done so already, fork the repo for the package (nano in this example) using the GitHub web UI or [`gh` cli tool](https://cli.github.com/manual/gh_repo_fork) from the `github-cli` package. It will be forked to `github.com/yourgithubaccount/nano`. +If you had not yet done so already, fork [getsolus/packages](https://github.com/getsolus/packages) using the GitHub web UI or [`gh` cli tool](https://cli.github.com/manual/gh_repo_fork) from the `github-cli` package. It will be forked to `github.com/yourgithubaccount/packages`. ### Update a Fork -If you already have a fork of the package in GitHub, from previous updates, log into GitHub. Make sure you're looking at the master branch. Check to see that your fork is up to date with the repo it was forked from. If your fork indicates it is behind, use the "Sync fork" button to bring it up to date. +If you already have a fork of [getsolus/packages](https://github.com/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 the package, change to your packaging directory, clone your fork and switch to its directory. For example: +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: ```bash cd ~/solus-builds -gh repo clone yourgithubaccount/nano -cd nano +gh repo clone yourgithubaccount/packages +cd packages/packages/n/nano ``` ### Update an existing clone @@ -46,8 +47,8 @@ cd nano If you already have a local clone, you need to bring it up to date. To do so run: ```bash -cd ~/solus-builds/package-name -git switch master +cd ~/solus-builds/packages/n/nano +git switch main git pull ``` @@ -64,7 +65,7 @@ git switch -c update_nano 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 `make bump`, which increments the release number by 1. +This can be achieved by doing `go-task bump`, which increments the release number by 1. ## Updating a Package @@ -93,7 +94,7 @@ 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 `make`. +After bumping or updating the package, build it by running `go-task`. Once your package has built successfully, you will need to [test it](testing-a-package). ## Commit Your Changes @@ -154,4 +155,4 @@ For more information on suitable commit messages, please check the [tooling cent - 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 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](submitting-a-pull-request.md). \ No newline at end of file +Next, you'll [submit a pull request for review](submitting-a-pull-request.md). diff --git a/docs/packaging/your-first-package-update.md b/docs/packaging/your-first-package-update.md index 5b44afe07..94016ea97 100644 --- a/docs/packaging/your-first-package-update.md +++ b/docs/packaging/your-first-package-update.md @@ -17,18 +17,17 @@ Change to your packaging directory. Your directory may have a different name or cd ~/solus-builds ``` -Clone the `nano` repository, then change into it: -The `make nano.clone` command will clone the `nano` package repository `https://github.com/solus-packages/nano` +Clone the `packages` repository, then change into it: ```bash -make nano.clone -cd nano +git clone https://github.com/getsolus/packages.git +cd packages/packages/n/nano ``` Increase the release number by one ("bump" the package) and then check the results: ```bash -make bump +go-task bump git diff ``` @@ -52,7 +51,7 @@ index 2ff1756..4bc344c 100644 Next, build the package: ```bash -make +go-task ``` You will be prompted to enter your password by sudo, and the `solbuild` tool will build the package.