Merge pull request #147 from pdsinterop/docs/depoy

Change deploy / publish instruction to live in a separate file.

README.md

@@ -29,32 +29,6 @@ There is a [GitHub Action](https://github.com/pdsinterop/solid-nextcloud/actions
 ## Manual testing
 You can try out the various Solid apps that show up in the Solid App GUI inside the Nextcloud GUI on first use.
 
-# Publishing to the Nextcloud app store
+### Build / Deploy
 
-* `git checkout main`
-* `git pull`
-* Tag v0.0.X in solid/appinfo/info.xml
-* `git tag`
-* `git tag v0.0.X`
-* `git push --follow-tags`
-* `git checkout publish`
-* `git pull`
-* `git merge main`
-* `cd solid`
-* `php ../composer.phar update`
-* `php ../composer.phar install --no-dev --prefer-dist`
-* `git commit -am"built"` (at least `vendor/composer/installed.php` will have changed)
-* `git push`
-* `cd ..`
-* create a release on github from the tag you just pushed
-* `tar -cf solid.tar solid/`
-* `gzip solid.tar`
-* `git checkout main`
-* edit the release and upload `solid.tar.gz` as a binary attachment
-* make sure transfer/solid.key and transfer/solid.crt exist
-* `openssl dgst -sha512 -sign ./transfer/solid.key ./solid.tar.gz | openssl base64`
-* visit https://apps.nextcloud.com/developer/apps/releases/new
-* go into the developer tools browser console to change the `<a>` element around the form to a `<p>` element. This makes it possible to fill in values in this form without being redirected.
-* fill in for instance `https://github.com/pdsinterop/solid-nextcloud/releases/download/v0.0.2/solid.tar.gz` and the base64 signature from the openssl command
-* click 'uploaden'
-* good luck!
+For publishing to the Nextcloud app store see [the deploy instructions](docs/deploy.md).

docs/deploy.md

@@ -0,0 +1,132 @@
+# Deploy Process
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Releasing a version](#releasing-a-version)
+  - [Opening an MR](#opening-an-mr)
+  - [Tagging a release](#tagging-a-release)
+- [Building a package](#building-a-package)
+  - [Installing dependencies](#installing-dependencies)
+  - [Creating a tarball](#creating-a-tarball)
+- [Deploying the package](#deploying-the-package)
+  - [Uploading the tarball](#uploading-the-tarball)
+  - [Creating a release in the Nextcloud App store](#creating-a-release-in-the-nextcloud-app-store)
+    - [Creating a signature](#creating-a-signature)
+    - [Adding the signature and link to the Nextcloud App store](#adding-the-signature-and-link-to-the-nextcloud-app-store)
+
+<!-- tocstop -->
+
+## Overview
+
+A _"**release**"_ in the Nextcloud App store consists of a URL where an archive lives (zip, tar, gz, etc.) and a SSL digest (or "signature") with which the integrity of the archive can be validated.
+
+To create a release, both the signature and the URL where the archive can be downloaded need to be posted to the App Store.
+The archive is created from the source-code in this repository.
+
+It is a common practice to create a _"**tag**"_, to clearly mark the point in code-base's history where the release has been created.
+But the source-code from which the archive is created is not enough _by itself_.
+
+The code also relies on other packages (some of which are created by PDS Interop) in order to function properly.
+Because of this, an extra _"**build**"_ step is required between tagging the code and creating the archive.
+
+Thus, to publish a release of this project to the Nextcloud app store, the following steps need to be taken:
+
+- Release a version of the code-base
+  - Open a release MR
+  - Tag a release
+- Build a package from the tagged release
+  - Install dependencies
+  - Create a tarball
+- Deploy the built package
+  - Upload the tarball to the GitHub Release page
+  - Create a release in the Nextcloud App store
+
+These steps are described in more detail below.
+
+## Releasing a version
+
+A release consists of two things:
+
+- A tag in git, annotated and signed
+- A release page on GitHub
+
+The tag is needed so a release page can be created. The release page is needed so there is a place where the tarball can live.
+Any changes that need to be made to the code-base for a release should live in a separate branch.
+These changes can be merged to the main branch by opening a merge-request (MR).
+Once the merge request has been merged, a tag can be created, as well as a release.
+
+### Opening an MR
+
+- Create a `release/v0.X.X` branch
+- Change anything that needs to be updated for a new release (at the least the version in `solid/appinfo/info.xml`)
+- Open an MR
+When the MR is merged a release version can be tagged by creating a GitHub Release
+
+### Tagging a release
+
+It is possible to create a tag locally, using the `git tag` command.
+However, this is not needed. When a release is created using the GitHub UI, a tag will be created automatically.
+Once that has been done, a package can be built from the release.
+
+## Building a package
+
+The "package" consists of an archived version of the `solid/` directory.
+
+Before a tarball can be created to use as package, various dependencies need to be installed.
+
+### Installing dependencies
+
+Currently, the dependencies this project has are satisfied by composer.
+
+They can be installed using:
+
+```sh
+# This command should be run in the `solid/` directory
+composer install --no-dev --no-interaction --no-plugins --no-scripts --prefer-dist
+```
+
+to make sure the provided dependencies are usable in the supported PHP versions, a docker image can be used.
+
+### Creating a tarball
+
+Once the dependencies are installed, an archive can be created using TAR:
+
+```sh
+# This command should be run from the project root
+tar --directory="${PWD}" --create --file 'solid.tar.gz' --gzip solid
+```
+
+## Deploying the package
+
+After the `solid.tar.gz` tarball has been created, it needs to be uploaded to the GitHub release page.
+
+### Uploading the tarball
+
+The tarball can be uploaded by editing the Release created on GitHub
+
+The tarball URL will be similar to `https://github.com/pdsinterop/solid-nextcloud/releases/download/v0.X.X/solid.tar.gz`
+
+### Creating a release in the Nextcloud App store
+
+#### Creating a signature
+
+Now that the tarball is available at a public URL, the "Upload app release" feature in the Nextcloud App Store can be used to create a release. In order to do so, a "Signature" needs to be created.
+
+⚠ Make sure `transfer/solid.key` and `transfer/solid.crt` exist, as these are both needed to create a signature.
+
+The command to create the signature is:
+
+```
+openssl dgst -sha512 -sign ./transfer/solid.key ./solid.tar.gz | openssl base64
+```
+
+#### Adding the signature and link to the Nextcloud App store
+
+The signature and URL should be added using the form at https://apps.nextcloud.com/developer/apps/releases/new
+
+Fill in the URL for the tarball from the GitHub release and the base64 signature from the openssl command.
+
+After clicking "upload" a new release _should_ have been created.
+
+This can be verified by visiting the app page in the store: https://apps.nextcloud.com/apps/solid