gamma-cli 0.4.7
Gamma toolbox
License: Apache License 2.0
Requires Python: >=3.7

# Gamma Toolbox

[![PyPI version](https://badge.fury.io/py/gamma-cli.svg)](https://badge.fury.io/py/gamma-cli)
![PyPI - Downloads](https://img.shields.io/pypi/dm/gamma-cli?style=plastic)
[![CircleCI](https://cci.gamma.bcg.com/gh/BCG/gamma-cli/tree/develop.svg?style=svg&circle-token=d614da7a99c91be0cd3cdfe7ea829ed56b5803cd)](https://cci.gamma.bcg.com/gh/BCG/gamma-cli/tree/develop)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=gamma-cli&metric=sqale_rating)](https://sonarcloud.io/dashboard?id=gamma-cli)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=gamma-cli&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=gamma-cli)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=gamma-cli&metric=security_rating)](https://sonarcloud.io/dashboard?id=gamma-cli)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=gamma-cli&metric=coverage)](https://sonarcloud.io/dashboard?id=gamma-cli)

Gamma's toolbox used to bootstrap new projects and for all the common operations.

Full documentation: <https://github.gamma.bcg.com/pages/BCG/gamma-cli/>

## Installation

You'll need Python >=3.7 installed in your system. A recent anaconda/miniconda setup
is also valid (please use the `base` conda environment). You can always check with:

`python3 --version` or `python --version`

If need to install/upgrade Python, see instructions for specific systems:

- Windows: https://www.python.org/downloads/windows
- Mac OSX: https://docs.python-guide.org/starting/install3/osx
- Debian/Ubuntu: `sudo apt install python3.8 python3-pip python3.8-venv`
- RedHat/CentOS: `sudo yum install python38 python38-pip`

### Recommended way (Mac/Linux)

Download and run the [install script](https://gamma.azureedge.net/cli/install) using
your `python3` interpreter.

```
curl -fs https://gamma.azureedge.net/cli/install -o gamma-cli-install
python3 gamma-cli-install
```


### Recommended way (Windows)

Download and run the [install script](https://gamma.azureedge.net/cli/install) using
your `python` interpreter. Using PowerShell:

```
Invoke-WebRequest -Uri https://gamma.azureedge.net/cli/install -outfile gamma-cli-install
python gamma-cli-install
```

### Manual installation

The recommended way of installing `gamma-cli` is as a self-contained user application
via [pipx](https://github.com/pipxproject/pipx).

1. Ensure you have a suitable `python` version >= 3.7 with `pip` and `venv` modules
   available:

```
python3 --version
python3 -m pip --version
python3 -m venv --help
```

2. Install `pipx` to the **user** site:

`python3 -m pip install --user pipx`

3. Restart your shell if needed. Then install `gamma-cli` using `pipx`

`pipx install gamma-cli`

## Usage

### to see the commands

`gamma`

### To login with Github

`gamma login`

you will be prompted your token, you need to create one on: <https://github.gamma.bcg.com/settings/tokens>

The token will be saved to be used with other commands

### To create a new project

`gamma new project`

`gamma new project --path /tmp/`

### To create a new Trello board

`gamma new trello`

### To request a new VM

`gamma new vm`

You will be prompted few options for your project then if you want to init
a git project and to push the first commit to Github.

### to check the licenses of the installed Python packages

`gamma check-licenses` to check the license in the current environnement


If `gamma-cli` is installed globally and you are using a virtual env (venv, conda,...), you need to indicate the path of the Python binary to use, for example on Linux and Mac:
```
gamma check-licenses -p `which python`
```

### to create a .gitignore file

`gamma gitignore options` to get the available options

`gamma gitignore generate python flask > .gitignore` to generate a .gitgnore file in the current directory

## Plugin subsystem

Gamma toolbox implements commands as loosely-coupled plugins, allowing people to extend
it's functionally without central coordination. It uses [pluggy](https://pluggy.readthedocs.io/en/latest/)
as the plugin framework.

Please check the [gamma.cli.plugins](gamma/cli/plugins.py) module for the plugin
subsystem specification, and [gamma.cli.commands](gamma/cli/commands/plugins.py) file
for the implementation of the built-in commands.

People interested in developing and packaging their own plugins for the Gamma toolbox
should check the _official_ sample plugin repository at
https://github.gamma.bcg.com/BCG/gamma-cli-sample-plugin

## DevOps

### Build && Update

Each push/PR to the project will be executed in Azure Devops, following this workflow:

![devops flow](https://i.imgur.com/Yv4joBu.png)

- Testing the project in Windows and Mac VM
- Running code analysis with <https://sonarcloud.io>
- Building and publishing the doc on <https://github.gamma.bcg.com/pages/BCG/gamma-cli/>
- Publishing the latest release on <https://pypi.org>
- updating the release number on the gist <https://gist.github.com/stumpyfr/b4f89c297a4e479049ff463fed790b37>, allowing the tool to propose the update to the users

### Update on client side

The tool is automatically checking at every run if a newer version exist and display
a warning to the user about the need to update.

The version if exposed here: <https://gist.github.com/stumpyfr/b4f89c297a4e479049ff463fed790b37>
and automatically updated by the CI when the project version is bump and a new release is published.

## Tests

The projects is using two types of test, both are combined to cover the test of the project from a technical point of view (TDD) and a functional point of view (BDD).

### Unit tests

`pytest` will execute all the unit tests, display the test coverage and generate the coverage file for the CI

### Business tests

`behave` will execute all the "functional" tests.

## telemetry

The project is sending telemetry of two types:

- usage with event for each actions (<https://azure.microsoft.com/en-us/services/monitor/)>
- exception in case of crash (<https://sentry.io>)

The data is used to allow us to understand the usage of the tool and be able to quickly fix issues.

If you want to opt-out from the telemetry, you need to use the `--no-telemetry` options or set the environement variable `NO_TELEMETRY=True`

## Code formater

The project is using `black` for the code formating: <https://github.com/psf/black>

## Version bumping

The project is using `punch` to handle the version bumping: <https://github.com/lgiordani/punch>