aspera-cli 4.15.0 → 4.16.0

data/CONTRIBUTING.md

@@ -42,32 +42,81 @@ Architecture:
 
 ![Architecture](docs/architecture.png)
 
-The entry point is lib/aspera/cli/main.rb
+The entry point is: `lib/aspera/cli/main.rb`.
 
-Plugins are located in lib/aspera/cli/plugins
+Plugins are located in: `lib/aspera/cli/plugins`.
 
-Transfer agents: lib/aspera/fasp
+Transfer agents, in: `lib/aspera/fasp`.
+
+## Ruby version
+
+Install ruby with [RVM](https://rvm.io).
+
+Cleanup installed gems in `rvm` to start fresh:
+
+```bash
+make cleanup_gems
+```
+
+## Tool chain
+
+TODO: document installation of tool chain.
+
+### Documentation
+
+Documentation is generated with `pandoc` and `LaTeX`.
+IBM font `Plex` is used, see [IBM Plex](https://www.ibm.com/plex/).
 
 ## Running Tests
 
-First, a testing environment must be created:
+First, a testing configuration file must be created, from project top folder:
 
 ```bash
-mkdir local
-cp docs/test_env.conf local/.
+mkdir ~/some_secure_folder
+cp docs/test_env.conf ~/some_secure_folder/.
 ```
 
-Fill `local/test_env.conf` with system URLs and credentials for tests.
+Fill `~/some_secure_folder/test_env.conf` with system URLs and credentials for tests.
 
-This project uses a Makefile for tests:
+Then tell where this file is located:
 
 ```bash
-cd tests
-make
+export ASPERA_CLI_TEST_CONF_FILE=~/some_secure_folder/test_env.conf
+```
+
+This project uses a `Makefile` for tests:
+
+```bash
+make test
 ```
 
 When new commands are added to the CLI, new tests shall be added to the test suite.
 
+### Special tests
+
+Some gems are optional: `rmagick` and `grpc`, as they require compilation of native code which may cause problems.
+By default, tests that use those gems are skipped.
+To run them: `make optional`.
+Those tests also require the optional gems to be installed: `make install_optional_gems`.
+
+Some other tests require interactive input. To run them: `make interactive`
+
+To run every test: `make full`
+
+### Pre-release tests
+
+For preparation of a release, do the following:
+
+1. Select a ruby version to test with: `rvm use 3.2.2`
+2. Remove all gems: `make clean_gems`
+3. Starts tests: `make test`
+4. Install optional gems: `make install_optional_gems`
+5. Test remaining cases: `cd tests` and then `make optional` and `make interactive`
+
+This ensures that optional gems do not prevent `ascli` to run.
+
+To test additional Ruby version, repeat the procedure with other Ruby versions.
+
 ## Coverage
 
 A coverage report can be generated in folder `coverage` using gem `SimpleCov`.
@@ -102,7 +151,7 @@ Then procedure is as follows:
   gem cert --build maintainer@example.com
   ```
 
-  > **Note:** the email must match the field `spec.email` in `aspera-cli.gemspec`
+  > **Note:** The email must match the field `spec.email` in `aspera-cli.gemspec`
 
   This creates two files in folder `/path/to/vault` (e.g. $HOME/.ssh):
   
@@ -111,7 +160,7 @@ Then procedure is as follows:
 
   > **Note:** Alternatively, use an existing key or generate one, and then `make new-cert`
 
-- The maintainer build the signed gem.
+- The maintainer builds the signed gem.
 
   The gem is signed with the public certificate found in `certs` and the private key (kept secret by maintainer).
 
@@ -187,26 +236,28 @@ A template is used as it allows some level of customization to tell where to tak
 Then, to push to the image registry (both tags: version and `latest`):
 
 ```bash
-make dpush
+make docker_push
 ```
 
 ### Specific version image build
 
-It is possible to build a specific version by setting envvar `GEM_VERSION` and `make` with option `-e`:
+To build a specific version: set envvar `GEM_VERSION` and `make` with option `-e`:
 
 ```bash
 GEM_VERSION=4.11.0 make -e docker
-GEM_VERSION=4.11.0 make -e dpush
+GEM_VERSION=4.11.0 make -e docker_push
 ```
 
+> **Note:** This does not use the gem locally, only the docker file is used locally, the gem is installed from rubygems.org.
+
 ### Development version image build
 
 To build/push a beta/development container:
-it does not create the `latest` tag, it uses the gem file generated locally.
+it does not create the `latest` tag, it uses the gem file generated locally with a special version number.
 
 ```bash
-make dockerbeta
-make dpushversion
+make docker_beta
+make docker_push_beta
 ```
 
 ## Single executable build