Reorganize packaging docs to match the workflow. (#373)

* Reorganize packaging docs to match the workflow.

Add useful links. Clarify wording. Move text blocks to where they make sense in the workflow.# Please enter the commit message for your changes. Lines starting

* Update docs/packaging/prepare-for-packaging.mdx

Correct  spelling of Solus.

Co-authored-by: Evan Maddock <[email protected]>

* Update docs/packaging/submitting-a-package.md

Fixed grammar.

Co-authored-by: Evan Maddock <[email protected]>

* Update docs/packaging/updating-an-existing-package.md

Grammatical fix.

Co-authored-by: Evan Maddock <[email protected]>

* Update docs/packaging/package.yml.md

Clarified wording.

Co-authored-by: Evan Maddock <[email protected]>

* Update docs/packaging/index.mdx

Fixed markdown formatting for the list

Co-authored-by: Evan Maddock <[email protected]>

* Iprovements after review

* Updates and corrections after second review

* Re-add MAINTAINERS.md template. Add references in creating and updating steps

* Update create package docs with more complete flow. Split off git basics to new file

* Logical flow improvements after review.

Further improve logical flow of steps in relation to forking.
Split git and testing info into separate documents.
Make commit info more consistent and applicable to new / updated packages

* Wording, link and format fixes after review and yarn lint. Update index.

* Workflow and grammatical fixes after review

* Further updates after review

- Make examples of packaging directory consistent
- Grammatical and formatting fixes
- Correct workflow details for creating a new package PR
- Changed commit template and git commit commands to be consistent with
  the PR template

---------

Co-authored-by: Tracey Clark <[email protected]>
Co-authored-by: Evan Maddock <[email protected]>

docs/packaging/_git_commit_cleanup.md

@@ -0,0 +1,18 @@
+:::note
+
+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.
+
+1. Set an alias in [`~/.gitconfig`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-alias) such as
+   ```bash
+   cs = commit --cleanup=scissors
+   ```
+  You can then use `git cs` which will do the same thing as `git commit --cleanup=scissors`.
+
+2. Set your git global config to always use the flag. To do so run
+```bash
+git config --global commit.cleanup scissors
+```
+
+:::

docs/packaging/_markdown-migration-warning.md

@@ -0,0 +1,8 @@
+:::danger
+
+We are currently in the process of migrating our source repositories from Phabricator to GitHub. If you have any repos checked out from Phabricator, [migrate them](docs/packaging/procedures/migrate-repos-to-github.md) before proceeding.
+
+Updating all facets of the documentation will take some time.
+If you notice any issues feel free to [file an issue](https://github.com/getsolus/help-center-docs/issues/new) on our docs tracker, or get in contact with us on our [Matrix](/docs/user/contributing/getting-involved#matrix-chat) channels.
+
+:::

docs/packaging/advanced-config/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Advanced Configuration",
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/packaging/local-repository.md → docs/packaging/advanced-config/local-repository.md

@@ -7,6 +7,10 @@ summary: Packaging Using a Local Repository
 
 This guide walks you through the steps necessary to tell solbuild how to utilise locally built `.eopkg's` that are not yet in the Solus repository.
 
+:::note
+It is not necessary to use a local repository to test most package submissions. The easier and recommended way is to install the eopkg files provided when a package is built. This is intended for use with stack upgrades, rebuilds, or new packages that need new dependencies that are not yet in the repo.
+:::
+
 We assume you have worked through the [packaging](/docs/packaging) material for creating a package with solbuild.
 
 ## Install the local profile

docs/packaging/creating-a-new-package.md

@@ -1,37 +1,97 @@
 ---
 title: Creating a New Package
-summary: Creating a New Package
+summary: Creating a Package For Inclusion in the Repositories
+sidebar_position: 3
 ---
 
 # Creating a New Package
 
-This page will take you through the steps required to build a new package on Solus. For this example, we will use the command line utility [tree](https://gitlab.com/OldManProgrammer/unix-tree), which is already packaged for Solus, but we will pretend like it's not.
+This page will take you through the steps required to build a new package for the Solus package repositories. For this example, we will use the command line utility [tree](https://gitlab.com/OldManProgrammer/unix-tree), which is already packaged for Solus, but we will pretend like it's not.
 
-## Create a new Package Directory
+:::note
 
-From within your build directory, create a new directory for the new package with the package name, and create the required Makefile within that directory:
+**Please [look to see if an issue has been filed](https://github.com/getsolus/packages/issues?q=label%3A%22Package+Request%22) for the software or library you intend to package**. If there is an existing request, please add a link to it in your pull request. Ex:
+
+```
+This PR resolves software 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 the repo [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 [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.
+
+## Clone the packages repo / update your clone
+
+### Clone the repo
+
+From within your packaging directory, clone the fork. Then, change to this directory.
+
+```bash
+cd ~/solus-builds
+gh repo clone yourgithubaccount/packages
+cd ~/solus-builds/packages
+```
+
+### Update an existing clone
+
+If you already have a local clone, you need to bring it up to date. To do this run:
+
+```bash
+cd ~/solus-builds/packages
+git switch master
+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:
 
 ```bash
 mkdir tree
 cd tree
+git switch -c your-branch
+```
+
+## Link to the `Makefile`
+
+Every package directory needs a `Makefile`. To create it with the proper contents, run this:
+
+```bash
 echo "include ../Makefile.common" > Makefile
 ```
 
+## Create The `MAINTAINERS.md` File
+
+You must add a file called `MAINTAINERS.md` using the template in [Maintainership](procedures/maintainership.md). Solus uses this to track the primary maintainer(s) for each package.
+
 ## Create the `package.yml` File
 
-Create a skeleton `package.yml` file using the `yauto.py` script from `common` You will need a link to the source tarball.   
-You can, of course, create your `package.yml` file entirely from scratch, but the script will give you a better starting point.
+You will need a link to the most recent source tarball for this from the software's website.
+
+Create a skeleton `package.yml` file using the script `common/Scripts/yauto.py` and the link for the tarball. For example:
 
 ```bash
 ../common/Scripts/yauto.py https://gitlab.com/OldManProgrammer/unix-tree/-/archive/2.1.1/unix-tree-2.1.1.tar.gz
 ```
 
-Consider creating an alias for this script in your `.bashrc` file.
+Consider creating an alias for this script in your `.bashrc` file (or equivalent for your preferred shell).
 
 ```bash
 alias fetchYml="$HOME/solus-builds/common/Scripts/yauto.py"
 ```
 
+:::note
+You can, of course, create your `package.yml` file entirely from scratch, but the script will give you a better starting point. We recommend using the script.
+:::
+
 Now you should have a `package.yml` file that looks something like this:
 
 ```yaml
@@ -40,6 +100,7 @@ version    : 2.1.1
 release    : 1
 source     :
     - https://gitlab.com/OldManProgrammer/unix-tree/-/archive/2.1.1/unix-tree-2.1.1.tar.gz : bcd2a0327ad40592a9c43e09a4d2ef834e6f17aa9a59012a5fb1007950b5eced
+homepage   : PLEASE FILL ME IN
 license    : GPL-2.0-or-later # CHECK ME
 component  : PLEASE FILL ME IN
 summary    : PLEASE FILL ME IN
@@ -54,15 +115,18 @@ install    : |
     %make_install
 ```
 
-The `yauto.py` script has filled many fields for us, but not all of them will be right, and some of them are blank. Refer to the [package.yml page](docs/packaging/package.yml.md) to see how each field should be used.
+The `yauto.py` script has filled many fields for us, but not all of them will be right, and some of them need to be filled in. Refer to the [package.yml page](docs/packaging/package.yml.md) to see how each field should be used.
 
 For this example, we need to fix the following:
 
+- The name needs to be `tree`, so update it.
 - The `license` is correct, so we remove the comment.
-- Fill in `component`, `summary`, and `description`.
-- Remove `builddeps`. This package has no builddeps beyond the ones already available for every package (the `system.devel` packages).
-- The `setup` step is not required.
-- We can't use the `%make_install` macro for this package, so the files are installed in there correct locations individually.
+- Fill in `homepage`, `component`, `summary`, and `description`.
+- Remove `builddeps`. This package has no build dependencies beyond the ones already available for every package (the `system.devel` packages).
+- The `setup` step is not required, remove it.
+- In the `install` key, we can't use the `%make_install` macro for this package. The files are installed in their correct locations individually.
+
+After updating the file, it will now look like:
 
 ```yaml
 name       : tree
@@ -83,16 +147,13 @@ install    : |
     install -Dm00755 $workdir/tree $installdir/usr/bin/tree
 ```
 
-Understanding how to translate source code into a good `package.yml` file is the heart of packaging. If you are stumped, or have questions, **ask for help on [Matrix](/docs/user/contributing/getting-involved#matrix-chat).**
-
-## Build the Package
+To read more about finding and including dependencies and other parts of `package.yml` please see [Packaging Practices](packaging-practices.md).
 
-Build the package:
+Understanding how to translate source code into a good `package.yml` file is the heart of packaging. If you are stumped, or have questions, **ask for help in our Solus Packaging room on [Matrix](/docs/user/contributing/getting-involved#matrix-chat).**
 
-```bash
-make
-```
+## Build the Package
 
+Build the package with `make`
 Once the build completes, your directory should now include the following files:
 
 ```text
@@ -104,4 +165,52 @@ Once the build completes, your directory should now include the following files:
 └── tree-2.1.1-1-1-x86_64.eopkg
 ```
 
-All these files _except_ the `*eopkg` file should be included when you submit the package for review.
+All these files _except_ the `*eopkg` file(s) should be included in your pull request. You will remove the `.eopkg` files after testing the package.
+
+Once your package has built successfully, you will need to [test it](testing-a-package).
+
+## Commit your Changes
+
+Check the [changes in your files](git-basics).
+
+[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 --cleanup=scissors`.
+
+import GitCommitCleanup from './_git_commit_cleanup.md';
+
+<GitCommitCleanup/>
+
+### Commit message format for new packages
+
+There should be a summary line (with the package name), a blank line, and then the rest of the commit message.
+
+- There should at the minimum be a summary and Test Plan.
+- Bullet point lists should start with a dash.
+
+Here is an example in our standard format (make sure to check the box in the checklist):
+
+```
+tree: initial inclusion in the repository
+
+## Summary
+
+Add the tree package, which recursively lists directories in a tree like manner.
+
+## 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](https://github.com/solus-project/tooling-central/blob/master/README.rst#using-git).
+
+- If you want to link this pull request to an existing package request, simply mention it in your commit message (use the full URL): `The inclusion of <somepackage> resolves 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).

docs/packaging/git-basics.md

@@ -0,0 +1,57 @@
+---
+title: Git Basics
+summary: Basic git commands for packaging
+---
+
+# Git Basics
+
+## Working with branches
+
+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
+
+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.
+You will need to fix any conflicts manually.
+You can check your branch against master with `git diff origin/master..my-branch`.
+
+## Adding files
+
+For every file you change or add, you must let git know about it: `git add someFile`
+
+## Removing files
+
+For files that need to be removed, you must do so using git: `git rm someFile`
+
+## Renaming files
+
+Likewise, for renaming a file, you must do so via git: `git mv someFile someFileName2`
+
+## Check the changes in your files
+
+It's a good idea to review the changes you have made to each file. This is to make sure you're committing what you intend and to make sure it looks good. Do this before adding changed files.
+
+To diff them all at once, useful for small changes, use `git diff`.
+To diff each file one at a time run `git diff filename` on each one.
+
+## Commit your changes
+
+**Check your branch**
+
+Get the status of the branch with `git status`. Make sure all the files you changed are staged, and that there are no untracked files. The git status should say your branch is clean.
+
+Now that you've tested and reviewed your change, when you're happy with it, it's time to commit your changes with `git commit`.
+
+## 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.
+
+```bash
+cd ~/solus-builds/package
+git switch master
+git branch -D my-branch
+git push -d origin my-branch
+```