aspera-cli 4.14.0 → 4.16.0

data/CONTRIBUTING.md

@@ -1,5 +1,5 @@
 # Contributing
-<!-- cspell:words passin GEMVERS -->
+<!-- cspell:words passin -->
 ## Reporting Issues and Vulnerabilities
 
 You can report issues at <https://github.com/IBM/aspera-cli/issues>
@@ -32,7 +32,7 @@ If you want to contribute, please:
 - Add tests for it. This is important so I don't break it in a future version unintentionally.
 - **Bonus Points** go out to anyone who also updates `CHANGELOG.md` :)
 - Send a pull request on GitHub.
-- run Rubocop to comply for coding standards
+- run `rubocop` to comply for coding standards
 
 ## Architecture
 
@@ -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 `GEMVERS` and `make` with option `-e`:
+To build a specific version: set envvar `GEM_VERSION` and `make` with option `-e`:
 
 ```bash
-GEMVERS=4.11.0 make -e docker
-GEMVERS=4.11.0 make -e dpush
+GEM_VERSION=4.11.0 make -e docker
+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
@@ -219,7 +270,7 @@ make single
 
 This is based on tool `rubyc` (gem `ruby-packer`): either place the executable in folder `tmp`, or the architecture-specific version will be automatically downloaded.
 
-> **Note:** Perl Findbin is needed, install on Linux with:
+> **Note:** Perl `Findbin` is needed, install on Linux with:
 
 ```bash
 sudo dnf install -y perl perl-FindBin perl-IPC-Cmd
@@ -231,4 +282,4 @@ sudo dnf install -y perl perl-FindBin perl-IPC-Cmd
   - <https://github.com/rest-client/rest-client>
   - <https://github.com/oauth-xx/oauth2>
 - use gem Thor <http://whatisthor.com/> (or other standard Ruby CLI manager)
-- Package a single-file executable for various architectures with <https://github.com/pmq20/ruby-packer> (rubyc)
+- Package a single-file executable for various architectures with <https://github.com/pmq20/ruby-packer> (`rubyc`)