From c9a1cce4dce48567b8047123e64a4bceba14bf2d Mon Sep 17 00:00:00 2001 From: Silke Hofstra Date: Tue, 24 Oct 2023 22:46:40 +0200 Subject: [PATCH] docs/packaging: Update documentation for Git hooks (#414) * docs/packaging: Update documentation for Git hooks - Add documentation about initializing the Git hooks - Update the packaging documentation information about the automated template. - Move the issue links to the PR to improve tracability in the packages project. * Update docs/packaging/prepare-for-packaging.md Co-authored-by: Evan Maddock <5157277+EbonJaeger@users.noreply.github.com> --------- Co-authored-by: David Harder Co-authored-by: Evan Maddock <5157277+EbonJaeger@users.noreply.github.com> --- docs/packaging/packaging-changes.md | 5 +++++ docs/packaging/prepare-for-packaging.md | 10 ++++++++++ docs/packaging/submitting-a-pull-request.md | 12 ++++++++++-- .../packaging/updating-an-existing-package.md | 19 +++++-------------- 4 files changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/packaging/packaging-changes.md b/docs/packaging/packaging-changes.md index 3e68e0324..2462b3673 100644 --- a/docs/packaging/packaging-changes.md +++ b/docs/packaging/packaging-changes.md @@ -15,6 +15,11 @@ This page is meant to serve as a changelog of sorts for the Solus packaging envi ### October +#### Git hooks + +Run `go-task init` to initialize Git hooks for the packages repository. +See [Prepare for packaging](prepare-for-packaging.md#initialize-git-hooks). + #### Requiring `homepage` in `package.yml` - The `homepage` key in `package.yml` has become mandatory. Use the address to the upstream source repository (eg: the GitHub page) if a package does not have a homepage. diff --git a/docs/packaging/prepare-for-packaging.md b/docs/packaging/prepare-for-packaging.md index cdb0dc00d..5bea1a14f 100644 --- a/docs/packaging/prepare-for-packaging.md +++ b/docs/packaging/prepare-for-packaging.md @@ -87,6 +87,16 @@ Create a local clone of the package repository you just forked. Here we are usin gh repo clone packages ~/solus-packages ``` +## Initialize Git hooks + +Initialize Git hooks for working with the repository by running: + +``` +go-task -d ~/solus-packages init +``` + +This makes it easy to create commits in the correct format, and will warn you about issues with changes you commit. + ## Set up Monorepo Helper Functions (Optional) After cloning your repo, create a symlink to source our bash shell helper functions diff --git a/docs/packaging/submitting-a-pull-request.md b/docs/packaging/submitting-a-pull-request.md index 83b606070..ef800e271 100644 --- a/docs/packaging/submitting-a-pull-request.md +++ b/docs/packaging/submitting-a-pull-request.md @@ -47,7 +47,15 @@ If you've created your own branch, as recommended, the cli tool will show you a Once the commit is successfully pushed, you'll notice that a URL will be provided that will immediately allow you to create a pull request with your changes. -Run `git status` one last time to make sure your branch is clean. If it is, open the link, double check everything, and create the pull request! +Run `git status` one last time to make sure your branch is clean. If it is: + +1. Open the link. +2. Fill in a summary of your changes (usually the same as the commit message). +3. Link any relevant issues: + - If you want to link this pull request to an existing issue, simply mention it in the PR summary: `The inclusion of fixes #123`. + - If you need a change to depend on another change, mention it in the PR summary too: `Depends on #234`. +4. Double check everything +5. Create the pull request! ## Amending a Pull Request @@ -90,4 +98,4 @@ If you need to make changes in response to a review, follow the steps in the [se Once your pull request is accepted and merged, someone on the Solus Team will issue a build. Your new / updated package will be published to the unstable repos. -At this point you may [delete the local and remote branches](git-basics#deleting-your-branch-after-a-pull-request-is-merged) for this pull request. \ No newline at end of file +At this point you may [delete the local and remote branches](git-basics#deleting-your-branch-after-a-pull-request-is-merged) for this pull request. diff --git a/docs/packaging/updating-an-existing-package.md b/docs/packaging/updating-an-existing-package.md index 09afa39d5..b533ed873 100644 --- a/docs/packaging/updating-an-existing-package.md +++ b/docs/packaging/updating-an-existing-package.md @@ -90,7 +90,10 @@ There should be a meaningful summary line (which starts with the package name), - 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): +`git commit` on [an initialized repository](prepare-for-packaging.md#initialize-git-hooks) will automatically open your editor with the correct template. +Note that lines starting with a `#` will be ignored by Git and do not need to be removed. + +Here is an example in our standard format: ``` foo: Update to 1.2.3 @@ -108,22 +111,10 @@ Enhancements: - 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 +- [1.2.3](https://github.com/foo/foo/releases/tag/v1.2.3) ``` For more information on suitable commit messages, please check the [tooling central documentation](https://github.com/solus-project/tooling-central/blob/master/README.rst#using-git). -- 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).