aspera-cli 4.24.2 → 4.25.0.pre

data/CONTRIBUTING.md

@@ -1,5 +1,5 @@
 # Contributing
-<!-- cspell:words passin -->
+
 ## Reporting Issues and Vulnerabilities
 
 If you encounter a problem or vulnerability, please report it at [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
@@ -10,7 +10,7 @@ Before submitting a new issue:
 
 To help us assist you efficiently, include the following in your report:
 
-- The version of ascli you are using:
+- The version of `ascli` you are using:
 
   ```bash
   ascli version
@@ -20,20 +20,22 @@ To help us assist you efficiently, include the following in your report:
 - The output of your Ruby environment:
 
   ```bash
-  ruby -e "puts RUBY_DESCRIPTION"
+  ruby -v
   ```
 
 ## Making Contributions
 
-We welcome contributions to improve the aspera-cli project!
+We welcome contributions to improve the `aspera-cli` project!
 
 ### Getting Started
 
-Clone the repository and navigate to the project folder:
+Clone the repository and navigate to the project's main folder:
 
 ```bash
 git clone https://github.com/IBM/aspera-cli.git
 cd aspera-cli
+bundle install
+bundle exec rake -T
 ```
 
 For testing instructions, refer to [Running Tests](#running-tests).
@@ -61,7 +63,7 @@ To submit a contribution:
 
 ## Architecture
 
-The overall architecture of aspera-cli is modular and extensible.
+The overall architecture of `aspera-cli` is modular and extensible.
 
 ![Architecture](docs/architecture.png)
 
@@ -84,12 +86,12 @@ A list of classes are provided in <docs/uml.png>
 ## Ruby version
 
 `aspera-cli` is built with Ruby.
-You can install Ruby using any method you prefer (e.g., rbenv, rvm, system package manager).
+You can install Ruby using any method you prefer (e.g., `rbenv`, `rvm`, system package manager).
 
-To start with a clean slate and remove all installed gems:
+To start with a clean state and remove all installed gems:
 
 ```bash
-make clean_gems
+bundle exec rake tools:clean_gems
 ```
 
 > [!TIP]
@@ -99,30 +101,28 @@ make clean_gems
 
 TODO: document installation of tool chain.
 
-Build system uses GNU Make.
+Build system uses Ruby's `rake`.
 
 ### Environment
 
 A few macros/env vars control some aspects:
 
-| `make` macro or Env var     | Description                          |
-|-----------------------------|--------------------------------------|
-| `ASPERA_CLI_TEST_CONF_FILE` | Path to configuration file with secrets for tests |
-| `ASPERA_CLI_TEST_MACOS`     | Set to `true` if local HSTS running on macOS      |
-| `ASPERA_CLI_TEST_PRIVATE`   | Path to private folder               |
-| `ASPERA_CLI_DOC_CHECK_LINKS`| Check links still exist during doc generation.    |
-| `ASPERA_CLI_DOC_DEBUG`      | Enable debug in doc generation.      |
-| `ENABLE_COVERAGE`           | Tests with coverage analysis if set. |
-| `SIGNING_KEY`               | Path to signing key to build Gem.    |
-| `GEM_VERSION`               | Gem version to build container       |
+| Environment variable        | Description                                        |
+|-----------------------------|----------------------------------------------------|
+| `ASPERA_CLI_TEST_CONF_FILE` | Path to configuration file with secrets for tests. |
+| `ASPERA_CLI_DOC_CHECK_LINKS`| Check links still exist during doc generation.     |
+| `LOG_LEVEL`                 | Change log level in `rake` tasks.                  |
+| `ENABLE_COVERAGE`           | Tests with coverage analysis if set.               |
+| `SIGNING_KEY`               | Path to signing key to build Gem.                  |
+| `GEM_VERSION`               | Override gem version for builds.                   |
 
-Those macros can be set either in an env var, or on the `make` command line.
+Those macros can be set either in an env var, or on the `rake` command line.
 
 > [!NOTE]
-> Env vars `ASPERA_CLI_TEST_*` are typically set in user's shell profile for development.
-> Others are more for "one shot" use.
+> Env vars `ASPERA_CLI_*` are typically set in user's shell profile for development.
+> Others are more for "one shot" use (on command line).
 
-To use the CLI directly from the development environment, add this to your shell profile:
+To use the CLI directly from the development environment, add this to your shell profile (adapt the real path):
 
 ```bash
 dev_ascli=$HOME/github/aspera-cli
@@ -153,100 +153,49 @@ To check URL during doc generation, set env var: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
 
 To debug doc generation, set env var: `ASPERA_CLI_DOC_DEBUG=debug`.
 
-## Running Tests
-
-First, a testing configuration file must be created.
-From project top folder, execute:
+## Test Environment
 
-```bash
-mkdir ~/some_secure_folder
-cp docs/test_env.conf ~/some_secure_folder/.
-```
+Refer to <tests/README.md>.
 
-Fill `~/some_secure_folder/test_env.conf` with system URLs and credentials for tests.
+## Build
 
-Then, tell where this file is located:
+The gem is built with:
 
 ```bash
-export ASPERA_CLI_TEST_CONF_FILE=~/some_secure_folder/test_env.conf
+bundle install
+bundle exec rake build
 ```
 
-This project uses a `Makefile` for tests, in main folder:
+If you don't want to install optional gems:
 
 ```bash
-make test
+bundle config set without optional
 ```
 
-When new commands are added to the CLI, new tests shall be added to the test suite in `tests/Makefile`.
-
-One can also go to the `tests` folder:
+Build beta version:
 
 ```bash
-cd tests
-make
-make full
-make list
-make torc
-make skip_torc
-make skip T=orch_wizard
+export GEM_VERSION=$(env -u GEM_VERSION rake tools:version).$(date +%Y%m%d%H%M)
 ```
 
-### 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.
-2. Remove all gems: `make clean_gems`
-3. `cd tests && make full`
-
-To test additional Ruby version, repeat the procedure with other Ruby versions.
-
-## Coverage
+### Signed gem
 
-A coverage report can be generated in folder `coverage` using gem `SimpleCov`.
-Enable coverage monitoring using macro/envvar `ENABLE_COVERAGE`.
-
-```bash
-cd tests
-make ENABLE_COVERAGE=1
-```
-
-Once tests are completed, or during test, consult the page: [coverage/index.html](coverage/index.html)
-
-## Build
-
-By default, the gem is built signed: `make`.
 A private key is required to generate a signed Gem.
-Its path must be set using macro/envvar `SIGNING_KEY`, see below.
-The gem is signed with the public certificate found in `certs` and the private key (kept secret by maintainer).
+Its path must be set using envvar `SIGNING_KEY`.
+The gem is signed with the public certificate found in `certs` and the private key pointed by `SIGNING_KEY` (kept secret by maintainer).
 
 ```bash
-make SIGNING_KEY=/path/to/vault/gem-private_key.pem
+bundle exec rake build SIGNING_KEY=/path/to/vault/gem-private_key.pem
 ```
 
-It is also possible to build an unsigned version for development purpose: `make unsigned_gem`.
-
-### Gem Signature
-
-Refer to <certs/README.md>
+Refer to <certs/README.md>.
 
 ### gRPC stubs for transfer SDK
 
 Update with:
 
 ```bash
-make grpc
+bundle exec rake tools:grpc
 ```
 
 It downloads the latest proto file and then compiles it.
@@ -255,20 +204,14 @@ It downloads the latest proto file and then compiles it.
 
 See [Container build](./container/README.md).
 
-For operations, move to the folder:
-
-```bash
-cd container
-```
-
 ## Single executable build
 
-See [Executable build](./binary/README.md).
+See [Executable build](build/binary/README.md).
 
-For operations, move to the folder:
+To list operations:
 
 ```bash
-cd binary
+bundle exec rake -T ^binary:
 ```
 
 ## Development check list for new release