aspera-cli 4.24.2 → 4.25.0

data/CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # 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).
+If you encounter a problem or a security vulnerability, please report it on [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
 
 Before submitting a new issue:
 
@@ -10,30 +10,32 @@ 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
   ```
 
-- Confirmation that you're using the latest version (update if not).
-- The output of your Ruby environment:
+- Confirmation that you are using the latest version (update it if needed).
+- Your Ruby version information:
 
   ```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 root directory:
 
 ```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).
@@ -48,7 +50,7 @@ To submit a contribution:
 
 1. **Implement** your feature or bug fix.
 
-1. **Write tests** to ensure your changes are robust and won’t break future versions.
+1. **Write tests** to ensure your changes are robust and prevent regressions.
 
 1. Run `rubocop` to ensure your code follows the Ruby style guide.
 
@@ -61,68 +63,64 @@ 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)
 
-Structure Highlights:
+### Structure Highlights
 
 - Entry Point:
 
-  `lib/aspera/cli/main.rb` - This is where the CLI execution begins.
+  `lib/aspera/cli/main.rb`, CLI startup logic.
 
 - Plugins:
 
-  Located in `lib/aspera/cli/plugins`, plugins extend CLI functionality and encapsulate specific features.
+  Located in `lib/aspera/cli/plugins`; plugins extend CLI functionality and encapsulate specific features.
 
 - Transfer Agents:
 
-  Found in `lib/aspera/agent`, these handle data transfers operations.
+  Found in `lib/aspera/agent`, these handle data transfer operations.
 
-A list of classes are provided in <docs/uml.png>
+Class diagrams are provided in <docs/uml.png>
 
-## Ruby version
+## Ruby Environment
 
-`aspera-cli` is built with Ruby.
-You can install Ruby using any method you prefer (e.g., rbenv, rvm, system package manager).
+`aspera-cli` is written in Ruby.
+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]
 > This is especially useful before testing across different Ruby versions or preparing for a release.
 
-## Tool chain
-
-TODO: document installation of tool chain.
+## Toolchain
 
-Build system uses GNU Make.
+The build system uses Ruby's `rake`.
 
 ### Environment
 
-A few macros/env vars control some aspects:
+A few macros and environment variables control certain aspects of the build:
 
-| `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_URL`  | URL for 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`           | Enable test coverage analysis when set.             |
+| `SIGNING_KEY`               | Path to the signing key used to build the gem file. |
+| `GEM_VERSION`               | Override gem version for builds.                    |
 
-Those macros can be set either in an env var, or on the `make` command line.
+These can be set either as environment variables or directly 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.
+> Environment variables `ASPERA_CLI_*` are typically set in the user’s shell profile for development.
+> Others are intended for use on the 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
@@ -134,9 +132,9 @@ export RUBYLIB=$dev_ascli/lib:$RUBYLIB
 
 Documentation is generated with `pandoc` and `LaTeX`.
 
-IBM font `Plex` is used, for installation see [IBM Plex](https://www.ibm.com/plex/).
+The IBM `Plex` font is used; for installation instructions, see [IBM Plex](https://www.ibm.com/plex/).
 
-On macOS to install `lualatex` and all packages:
+On macOS, to install `lualatex` and all packages:
 
 ```bash
 brew install texlive
@@ -149,138 +147,155 @@ tlmgr update --self
 tlmgr install fvextra selnolig lualatex-math
 ```
 
-To check URL during doc generation, set env var: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
+To check URLs during documentation generation, set the environment variable: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
+
+To debug documentation generation, set the environment variable: `ASPERA_CLI_DOC_DEBUG=debug`.
 
-To debug doc generation, set env var: `ASPERA_CLI_DOC_DEBUG=debug`.
+## Test Environment
 
-## Running Tests
+Refer to <tests/README.md>.
+
+## Build
 
-First, a testing configuration file must be created.
-From project top folder, execute:
+The unsigned gem is built with:
 
 ```bash
-mkdir ~/some_secure_folder
-cp docs/test_env.conf ~/some_secure_folder/.
+bundle install
+bundle exec rake unsigned
 ```
 
-Fill `~/some_secure_folder/test_env.conf` with system URLs and credentials for tests.
-
-Then, tell where this file is located:
+If you don't want to install optional gems:
 
 ```bash
-export ASPERA_CLI_TEST_CONF_FILE=~/some_secure_folder/test_env.conf
+bundle config set without optional
 ```
 
-This project uses a `Makefile` for tests, in main folder:
+To build a beta version:
 
 ```bash
-make test
+export GEM_VERSION=$(env -u GEM_VERSION rake tools:version).$(date +%Y%m%d%H%M)
 ```
 
-When new commands are added to the CLI, new tests shall be added to the test suite in `tests/Makefile`.
+### Signed gem
 
-One can also go to the `tests` folder:
+A private key is required to generate a signed gem.
+Its path must be set using environment variable `SIGNING_KEY`.
+The gem is signed with the public certificate found in `certs` and the private key specified by `SIGNING_KEY` (kept secret by the maintainer).
 
 ```bash
-cd tests
-make
-make full
-make list
-make torc
-make skip_torc
-make skip T=orch_wizard
+bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
 ```
 
-### Special tests
+Refer to <certs/README.md>.
 
-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`.
+### gRPC stubs for transfer SDK
 
-Some other tests require interactive input. To run them: `make interactive`
+Update with:
 
-To run every test: `make full`
+```bash
+bundle exec rake tools:grpc
+```
 
-### Pre-release tests
+It downloads the latest `proto` file and then compiles it.
 
-For preparation of a release, do the following:
+## Container image build
 
-1. Select a ruby version to test with.
-2. Remove all gems: `make clean_gems`
-3. `cd tests && make full`
+See [Container build](./container/README.md).
 
-To test additional Ruby version, repeat the procedure with other Ruby versions.
+## Single executable build
 
-## Coverage
+See [Executable build](build/binary/README.md).
 
-A coverage report can be generated in folder `coverage` using gem `SimpleCov`.
-Enable coverage monitoring using macro/envvar `ENABLE_COVERAGE`.
+To list operations:
 
 ```bash
-cd tests
-make ENABLE_COVERAGE=1
+bundle exec rake -T ^binary:
 ```
 
-Once tests are completed, or during test, consult the page: [coverage/index.html](coverage/index.html)
+## Release
 
-## Build
+### Branching Strategy
 
-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).
+This project uses a single `main` branch for development. During the development cycle, the version in `lib/aspera/cli/version.rb` uses a `.pre` suffix (e.g., `x.y.z.pre`) to indicate a pre-release state.
 
-```bash
-make SIGNING_KEY=/path/to/vault/gem-private_key.pem
-```
+Feature development and bug fixes can be done either:
 
-It is also possible to build an unsigned version for development purpose: `make unsigned_gem`.
+- Directly on `main` for small changes
+- Via feature branches with pull requests for larger changes
 
-### Gem Signature
+### Checklist Before a New Release
 
-Refer to <certs/README.md>
+When preparing for a new release, do the following:
 
-### gRPC stubs for transfer SDK
+- Run the test suite:
 
-Update with:
+```bash
+bundle exec rake test:run
+```
+
+- Verify that the container builds successfully (using the beta version):
 
 ```bash
-make grpc
+export GEM_VERSION=$(env -u GEM_VERSION rake tools:version).$(date +%Y%m%d%H%M)
+bundle exec rake container:build
+bundle exec rake container:test
 ```
 
-It downloads the latest proto file and then compiles it.
+### Automated Release Process
 
-## Container image build
+Releases are triggered via the GitHub Actions UI using the **Release** workflow (`.github/workflows/release.yml`).
 
-See [Container build](./container/README.md).
+To create a release:
 
-For operations, move to the folder:
+1. Navigate to **Actions** > **Release** in the GitHub repository
+2. Click **Run workflow**
+3. Optionally specify:
+   - **Release version**: The version to release. If left empty, uses the current version from `version.rb` without the `.pre` suffix.
+   - **Next development version**: The next version to prepare for. If left empty, auto-increments the minor version. The `.pre` suffix is added automatically.
+4. Click **Run workflow**
 
-```bash
-cd container
-```
+The workflow automatically:
 
-## Single executable build
+1. Updates `version.rb` with the release version
+2. Rebuilds documentation (PDF manual, README)
+3. Commits the changes
+4. Creates and pushes the release tag
+5. Triggers the deploy workflow to publish to [rubygems.org](https://rubygems.org/gems/aspera-cli)
+6. Updates `version.rb` to the next development version with `.pre` suffix
+7. Commits and pushes the version bump
 
-See [Executable build](./binary/README.md).
+### Manual Release Process (Alternative)
 
-For operations, move to the folder:
+If needed, releases can still be done manually:
 
-```bash
-cd binary
+- Update the version in `lib/aspera/cli/version.rb` (remove `.pre` suffix)
+
+- Build the PDF manual in `pkg`:
+
+```shell
+bundle exec rake doc:build
+```
+
+- Build the signed `.gem` in `pkg`:
+
+```shell
+bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
 ```
 
-## Development check list for new release
+- Create the release version tag and push it to GitHub:
+
+```shell
+bundle exec rake release_tag
+```
 
-When preparing for a new release do the following:
+This will trigger the action `.github/workflows/deploy.yml`, which builds the gem file and pushes it to RubyGems.
 
-- TODO
+- After release, update `version.rb` to the next development version with `.pre` suffix
 
-## Long Term Implementation and delivery improvements
+## Long‑Term Implementation and Delivery Improvements
 
-- replace Rest and OAuth classes with ruby standard gems:
+- Replace custom REST and OAuth classes with standard Ruby gems:
   - <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)
-- look at <https://github.com/phusion/traveling-ruby>
+- Use the `thor` gem <http://whatisthor.com/> (or other standard Ruby CLI manager)
+- Look at <https://github.com/phusion/traveling-ruby>