Merge pull request #39 from ikeydoherty/arcanist-phab

Document Phabricator changes

packaging/building-a-package/en.md

@@ -42,7 +42,7 @@ To update solbuild, run: `sudo solbuild update`
 
 Next you need to set up `common`, a set of make scripts that enables you to more easily manage, build, check, and publish packages.
 
-You need to clone the common repository with git `sudo eopkg it git` by doing `git clone https://git.solus-project.com/common` in the same directory you will have sub-folders for packages you are building.
+You need to clone the common repository with git `sudo eopkg it git` by doing `git clone https://dev.solus-project.com/source/common.git` in the same directory you will have sub-folders for packages you are building.
 
 Next you need to set up symlinks. Do this from the same directory you executed the `git` command:
 
@@ -77,7 +77,7 @@ make
 
 You will be prompted to enter your password by sudo so dependencies may be downloaded and the necessary eopkg files may be generated.
 
-You may find other `common` commands [here](https://git.solus-project.com/common/about/).
+You may find other `common` commands [here](https://dev.solus-project.com/source/common/browse/master/about/).
 
 Once you’ve achieved a successful build, the resulting `.eopkg` files will be moved to the current directory, along with the machine file, `pspec_*.xml` (currently `pspec_x86_64.xml`). We recommending checking the contents of your 
-generated eopkg file(s) to ensure everything is located in the appropriate locations. You can do this by using `lseopkg file_name.eopkg`.
+generated eopkg file(s) to ensure everything is located in the appropriate locations. You can do this by using `lseopkg file_name.eopkg`.

packaging/submitting-a-package/en.md

@@ -5,14 +5,107 @@ title = "Submitting the Package"
 
 This article will walk you through submitting a patch for a package for review and inclusion in the Solus repository.
 
-When sending patches to include your package in our repo, note that we do not accept binary files. We will need the `package.yml`, the `pspec_*.xml`, the `Makefile`, any ABI files generated, as well as the 
+When contributing patches to Solus, please note that we do not accept the upload of binary files (i.e. `.eopkg`).
-`files/` directory if applicable included within the patch. These patches are required to be [git format patches](https://git-scm.com/docs/git-format-patch) and submitted to the Patch Submissions Tag, in 
+All repository packages are built by a dedicated build server, from the source files provided in your patch upload.
-Maniphest, on our [Developer Portal](https://dev.solus-project.com).
 
-To generate a patch, first ensure your package directory is a git repo by running `git init`. Next, use `git add filename` to add files, where filename is, for example, the package.yml. Next, do `git commit` and 
+At minimum, your patch will include changes for the following:
-write an appropriate commit message, such as "Initial commit of packagename".
+
+ * `package.yml`
+ * `pspec_*.xml`
+
+If any additional files were required for the build, then you must also include the `files/` directory.
+If you are creating a new package, you will also need to include a `Makefile` containing the following text:
+
+```
+include ../Makefile.common
+```
+
+Lastly, many package builds may result in the generation of an ABI report. These files start with `abi_*` and must also
+be included, as they allow simple tracking of changes to symbols and dependencies.
+
+For all patch submissions you must be using the `arcanist` utility to communicate with the [Solus Developer Portal](https://dev.solus-project.com/)
+
+## Setting up Arcanist
+
+In three easy steps, you can set up arcanist for the first time:
+
+```
+sudo eopkg it arcanist
+arc set-config default https://dev.solus-project.com
+arc install-certificate
+```
+
+On the third step you will be given a unique link to log into the Developer Portal, to create a `Conduit API Token`. This
+token will be used to allow the CLI `arc` utility to communicate with Phabricator.
+
+
+## Creating the patch
+
+For every file you change or add, you must let git know about them:
+
+```
+git add someFile
+```
+
+For files that must be removed, you must do so using git:
+
+```
+git rm someFile
+```
+
+Likewise, for renaming a file, you must do so via git:
+
+```
+git mv someFile someFileName2
+```
+
+Once you're happy with your change, and you have verified locally that it works by having first built and
+installed it, it's time to commit your changes.
+
+```
+git commit
+```
+
+Make sure you provide a meaningful summary and a separate body to your commit message. 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 patch to an issue on the Developer portal, simply mention it in your commit message:
+
+```
+The inclusion of <somepackage> fixes T1234
+```
+
+
+If you need a change to depend on another change, mention it in the commit message too:
+
+```
+Depends on D5
+```
+
+Now you have your git commit, it's time to send it to us for review. Using the CLI again, simply issue:
+
+```
+arc diff
+```
+
+A new editor session will open, where you can provide optional details. Note that the default reviewer will
+be assigned after you submit, so it is not necessary to specify anyone here. Once you're finished, save and
+exit the editor (`CTRL+O` + `CTRL+X` for nano), and the patch will then be uploaded. You'll be presented
+with the Differential URL, and a review will happen as soon as possible.
+
+## Fixing a patch that needs changes
+
+That's easy. Don't make a new commit, just make any relevant changes to your local tree, adding + removing as
+before, but this time run:
+
+```
+git commit --amend
+```
+
+This will amend your original changes, and you can submit the patch once more with `arc diff`. The web UI will
+automatically update with the latest patch, without having to create any new tasks. Once accepted, your patch
+will be merged, and a build will be issued.
 
-Once a git commit is made, use `git format-patch -n1` to create a .patch file.
 
 ## Maintainership
 
@@ -26,4 +119,4 @@ over to a repository.
 
 Currently, the request mechanism [contact Ikey on IRC](/articles/contributing/getting-involved/en). It is far easier to grant access to active community members than those unknown to the project.
 
-Finally, note that the management reserve the right to revoke access at any time, in order to preserve project safety and integrity.
+Finally, note that the management reserve the right to revoke access at any time, in order to preserve project safety and integrity.

packaging/updating-an-existing-package/en.md

@@ -5,7 +5,7 @@ title = "Updating an Existing Package"
 
 This article will go over updating a package that is already in the Solus git repository.
 
-The instructions below assume you have cloned the package's repository using the http link provided on the respective git page, [for example nano](https://git.solus-project.com/packages/nano). The process for submitting an updated package is the same as if it is a new package. Follow the steps [here](/articles/packaging/submitting-a-package/en).
+The instructions below assume you have cloned the package's repository using the http link provided on the respective git page, [for example nano](https://dev.solus-project.com/source/nano/). The process for submitting an updated package is the same as if it is a new package. Follow the steps [here](/articles/packaging/submitting-a-package/en).
 
 ## Bumping a packaging
 
@@ -32,4 +32,4 @@ Example:
 
 ``` bash
 /usr/share/ypkg/yupdate.py 1.0 http://example.com/example-1.0.tar.xz
-```
+```

software/powerline-shell-prompt/en.md

@@ -7,8 +7,8 @@ title = "Powerline Shell Prompt"
 
 ## Installation 
 
-Powerline has two components, the plugin system itself ([powerline](https://git.solus-project.com/packages/powerline/)) and the 
+Powerline has two components, the plugin system itself ([powerline](https://dev.solus-project.com/source/powerline/)) and the 
-fonts ([powerline-fonts](https://git.solus-project.com/packages/powerline-fonts)). Both are available in the Software Center or via eopkg in a terminal:
+fonts ([powerline-fonts](https://dev.solus-project.com/source/powerline-fonts/)). Both are available in the Software Center or via eopkg in a terminal:
 
 ``` bash
 sudo eopkg it powerline powerline-fonts