# neetob

The `neetob` gem gives different commands for interacting with Github repos, Heroku instances and other tools to manage the workflow of neeto products.

## Table of Contents

1. [Usage](#usage)
   1. [Installing neetob for use](#installing-neetob-for-use)
   2. [For development](#for-development)
   3. [Gem release](#gem-release)
2. [Source of truth](#source-of-truth)
3. [Working with GitHub](#working-with-github)
   1. [Issues](#issues)
   2. [Labels](#labels)
   3. [Search](#search)
   4. [Protect Branch](#protect-branch)
   5. [Make PR](#make-pr)
   6. [Gems](#gems)
   7. [Login](#login)
5. [Working with Heroku](#working-with-heroku)
   1. [Config Vars](#config-vars)
   2. [Access](#access)
   3. [Execute](#execute)
5. [Working with Users](#working-with-users)
   1. [Audit](#audit)
   2. [Commits](#commits)
6. [Make Repos Uptodate](#make-repos-uptodate)
7. [Working with local Repos](#working-with-local-repos)
   1. [ls](#ls)
8. [Testing](#testing)

## Usage

### Installing neetob for use

Install and update the gem using the following command:

```sh
gem install neetob && gem update neetob
```

Use the `help` keyword to access a list of all the available commands and options.

```
neetob help

Commands:
  neetob github          # Interact with any resource in Github
  neetob help [COMMAND]  # Describe available commands or one specific command
  neetob heroku          # Interact with any resource in Heroku
  neetob users           # Interact with the contributors of neeto apps
  neetob make-repos-uptodate # Update all neeto repos

Options:
  [--sandbox] # All the commands in sandbox mode will run only on the "neeto-dummy" app.
```

#### Useful command-line options

| Option       | Meaning                           |
| ------------ | --------------------------------- |
| --apps       | Target app names                  |
| --sandbox    | Sandbox mode                      |
| --no-sandbox | Non-Sandbox mode                  |
| --help       | Provides information on a command |

The commands within `neetob` should be used with caution, as improper usage may result in unintended consequences, and some actions may not be reversible. By default, all commands will be executed in non-sandbox mode.

### For development

Clone the repository onto your system using the following command:

```sh
git clone https://github.com/bigbinary/neetob.git
```

Navigate to the root of the application directory.

```sh
cd neetob
```

To check and use the latest changes in the local repository install `neetob` like so:

```sh
bin/setup
```

We can use, check or debug the `neetob` locally by directly invoking the `neetob` class like so:

```sh
ruby exe/neeetob
```

#### Conventional commit messages

In `neetob` we are using the Google's [release please](https://github.com/googleapis/release-please) Github action to auto update the version and release the latest gem.

In order to make this action work we have to use the [conventional commit messages](https://www.conventionalcommits.org/en/v1.0.0/).

The Conventional commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history.

Generally, we use three types of suffix in the commit messages that are as follows:

1. `fix:` for the commit that fixes a bug in the codebase. This updates the third digit in the version. For example, `0.1.0` version will be updated to `0.1.1`.

2. `feat:` for the commit that introduces a new feature to the codebase. This updates the second digit in the version. For example, `0.1.0` version will be updated to `0.2.0`.

3. `BREAKING CHANGE:` for the commit that introduces a breaking API change. This updates the first digit in the version. For example, `0.1.0` version will be updated to `1.0.0`.

For more details please refer [official docs](https://www.conventionalcommits.org/en/v1.0.0/) from Conventional commits.

In `neetob` we use "squash and merge" option while merging the PR. So we have to update the commit message while squash and merge so that Github action can track that merge commit.

For example:

![Commit message update](images/commit-message-update.png)


### Gem release

When a commit is added to the `main` branch [release](.github/workflows/release.yml) Github action checks that commit for the [conventional commit message](#conventional-commit-messages). If a proper suffix like `fix:`, `feat:`, etc is used in that commit message then the Github action will create a new PR with the updated version and changelog. The version and changelog for the `neetob` gem are updated automatically by the Github action using the commit message. When we merge this newly created PR by the Github action into the main branch, an updated Gem is released to the [rubygems](https://rubygems.org).

## Source of truth

This [list of repos](https://github.com/bigbinary/neeto-compliance/blob/main/data/neeto_repos.json) is used as the "source of truth".

## Passing list of heroku apps as option

`neetob` allows you to pass list of apps in the following three formats.

```
// all staging heroku instances
--apps "neeto-*-staging"

// all production heroku instances
--apps "neeto-*-production"

// all staging and production instances
--apps "neeto-*-web"

// for local testing
--apps neeto-dummy
```

For safety reasons all the examples given below would be using `--apps neeto-*-staging`.

## Working with GitHub

Check the list of all the available subcommands for the `github` command by utilizing the `help` keyword.

```sh
neetob github help
```

### Issues

```sh
# Lists and counts all the open issues that are currently unassigned
neetob github issues list --count --state open --assignee none --apps "neeto-*-staging"

# Lists, counts and filters all unassigned open issues that are labeled as "bug"
neetob github issues list --count --label bug --state open --assignee none \
--apps "neeto-*-staging"
```

### Labels

The `labels` command provides an interface for interacting with Github labels.

```sh
# Lists the details of all the labels in the Github repo
neetob github labels list --apps "neeto-*-staging"

# Provides the details for a specific label in the Github repo
neetob github labels show --name priority --apps "neeto-*-staging"

# Changes the name of the label
neetob github labels update --old-name "High Priority" --new-name \
"high-priority" --all-neeto-repos

# Updates and inserts all the labels mentioned in the file "data/github-labels.json"
neetob github labels upsert --all-neeto-repos

# Accepts a different JSON file using `path` option
neetob github labels upsert --path ~/Desktop/labels.json --apps "neeto-*-staging"

# Upsert a single label using `name`, `color`, and `description` options
# No `#` is required while adding `color`
neetob github labels upsert --name UI --color 8250df --description \
"UI work needed" --all-neeto-repos

# Deletes the given labels from the Github repos
neetob github labels delete --labels "High Priority" "Priority 1" "bug" \
--apps "neeto-*-staging"

# Deletes all the labels from the Github repos
neetob github labels delete_all --apps "neeto-*-staging"
```

Check out the default labels [file](data/github-labels.json) for the required JSON file structure.

Don't use `#` before the color code.

```
{
  "name": "0.25D",
  "description": "Estimate - 2 hours",
  //"color": "#9E800A", // Wrong usage
  "color": "9E800A" // Correct usage
}
```

### Search

Searches for keywords across multiple neeto projects within specified files by utilizing the `search` command.

```sh
neetob github search --keyword neeto --path README.md --apps "neeto-*-staging"
```

### Protect branch

Updates branch protection rules in neeto repos by using the `protect_branch` command.

```sh
neetob github protect_branch --branch main --apps "neeto-*-staging"
```

By default, file "data/branch-protection-rules.json" will be used for updating the branch protection rules.

The `protect_branch` command can also be used with a different JSON file using `path` option.

For example, assume we have a file named `branch-protection-rules.json` on the `Desktop` with the following rules:

```json
{
  "required_conversation_resolution": true,
  "has_required_deployments": true
}
```

To update the above-mentioned branch protection rules for the `main` branch of all the neeto products, use the following command:

```sh
neetob github protect_branch --branch main --path ~/Desktop/branch-protection-rules.json \
--apps "neeto-*-staging"
```

We can also use the `--all-neeto-repos` option with the above mentioned command so that the
branch protection rules can be updated for
all [neeto repos](https://github.com/bigbinary/neeto-compliance/blob/main/data/neeto_repos.json).

```sh
neetob github protect_branch --branch main --path ~/Desktop/branch-protection-rules.json \
--all-neeto-repos
```

**Note:** Unfortunately, utilizing the Github API, we are unable to update the `Require deployments to succeed before merging` rule, as it is currently not defined as a parameter within the API. For further information on available options to update different branch protection rules, kindly refer to the official Github [documentation](https://docs.github.com/en/rest/branches/branch-protection#update-branch-protection).

### Make PR

The `make-pr` command creates pull requests across Github repos.

```sh
# The `compliance-fix` command runs `bundle install` and
# `bundle exec neeto-audit -a` inside all repos and create a PR.
neetob github make-pr compliance-fix

# Fix compliance for nanos
neetob github make-pr compliance-fix --nanos

# The `script` command runs the given script for each product and create a PR
neetob github make-pr script --path ~/Desktop/fix-folders.sh --branch "neetob-test" \
--title "PR title" --description "PR description"
```

### Gems

The `gems release` command releases the lastest gem for all neeto nanos.

```sh
# Releases the latest gem for all nanos
neetob github gems release

# Releases the latest gem for given nanos
neetob github gems release --nanos neeto-monitor-ruby neeto-bugtrap-ruby
```

### Login

Authenticate through your browser and update your Github access token by utilizing the `login` command.

```sh
neetob github login
```

## Working with Heroku

Utilize the `help` command to list all the available subcommands under the Heroku module for interacting with the Heroku resources.

```sh
neetob heroku help
```

### Config vars

The `config_vars` command interacts with Heroku config variables.

```sh
# The `list` command lists all the Heroku config variables
neetob heroku config_vars list --apps "neeto-*-staging"

# List specific Heroku config variables using `keys` option
neetob heroku config_vars list --apps "neeto-*-staging" --keys key1 key2  key3

# List specific Heroku config variables using a file
# Checkout the `data/config-vars-list.json` file for the required structure
neetob heroku config_vars list --apps "neeto-*-staging" --path \
neetob/data/config-vars-list.json

# The `audit` command checks the config variables against the JSON file named as
# `required-config-vars.json` that is present inside the `data` directory at the root of
# installed `neetob` gem
neetob heroku config_vars audit --apps "neeto-*-staging"

# The `audit` command also works with a different JSON file using `--path` option
neetob heroku config_vars audit --path ~/Desktop/config.json --apps "neeto-*-staging"

# The `upsert` command adds or updates config variables from the
# `data/config-vars-upsert.json` file present at the root of installed `neetob` gem
neetob heroku config_vars upsert --apps "neeto-*-staging"

# The `remove` command deletes config variables
neetob heroku config_vars remove --keys=TEST_KEY_1 TEST_KEY_2 --apps "neeto-*-staging"
```

We can use a custom JSON file with `upsert` command using the `--path` option.

For example, assume we have a file named `config.json` on the Desktop, like so:

```json
{
  "NEETO_WIDGET_API_KEY": "jh4c1SC5cS5BvRbcBk4LD",
  "NEETO_KB_API_KEY": "Lxh7vUKkRewfxSg4dg834",
  "NEETO_CHAT_API_KEY": "sYnMTSCWLxkNbkHRXL1Xtd"
}
```

To update the above-mentioned config variables to all staging apps, we can use the `upsert` command like so:

```sh
neetob heroku config_vars upsert --path ~/Desktop/config.json --apps "neeto-*-staging"
```

The `upsert` command can also update or insert project-specific config variables.

For example, assume we have a file named `config.json` on the `Desktop` with the following properties:

```json
{
  "neeto-chat-web-staging": {
    "NEETO_WIDGET_API_KEY": "jh4c1SC5cS5BvRbcBk4LD"
  },
  "neeto-testify-web-production": {
    "NEETO_KB_API_KEY": "Lxh7vUKkRewfxSg4dg834"
  },
  "neeto-desk-web-staging": {
    "NEETO_CHAT_API_KEY": "sYnMTSCWLxkNbkHRXL1Xtd"
  }
}
```

To update the above-mentioned config variables under the defined project, we can use the upsert command like so:

```sh
neetob heroku config_vars upsert --path_with_project_keys ~/Desktop/config.json --apps "neeto-*-staging"
```

### Access

The `access` command list, add and remove users from multiple Heroku apps.

```sh
# List all the users from Heroku apps
neetob heroku access list --apps "neeto-*-staging"

# Add new users to the Heroku apps
neetob heroku access add --users oliver@bigbinary.com eve@bigbinary.com --apps "neeto-*-staging"

# Remove the users from the Heroku apps
neetob heroku access remove --users oliver@bigbinary.com eve@bigbinary.com --apps \
"neeto-*-staging"
```

### Execute

The `execute` command executes a Heroku CLI command or a Rails console command for multiple neeto apps in one go.

```sh
# Execute Heroku CLI command
neetob heroku execute -c "heroku access" --apps "neeto-*-staging"

# Execute Rails console command
neetob heroku execute -c "Sidekiq::Cron::Job.destroy \"server_side_worker\"" --apps \
"neeto-*-staging" --rails
```

## Working with users

The `users` command interacts with the contributors of neeto applications.

### Audit

The `audit` command checks the contributors across all neeto applications for multiple emails and third-party domain emails.

```sh
# Audit all the contributors
neetob users audit
```

### Commits

The `commits` command lists the commits for a user in a defined duration.

```sh
# The below mentioned command will open a list of all the commits across neeto
# product repos made by "udai1931" in the duration of last 6 months
neetob users commits --author udai1931 --duration 6.months

# List commits for a specific product using `--apps` option
neetob users commits --author udai1931 --duration 6.months --apps neeto-kb-web

# List commits for all neeto repos using the `--all-neeto-repos` option
neetob users commits --author udai1931 --duration 6.months --all-neeto-repos
```

## Make Repos Uptodate

The `make_repos_uptodate` command updates all neeto repos.

```sh
neetob make_repos_uptodate

# Update all neeto repos with `--all-neeto-repos`
neetob make_repos_uptodate --all-neeto-repos
```

Executing the above mentioned command will check and clone all the missing neeto repos in the current working directory and will update all of them to the latest version. After the execution of command the directories will look something like this:

```
neeto-chat-web
neeto-desk-web
neeto-kb-web
```

## Working with local Repos

The `local` command interacts with the local neeto repos.

### ls

The `ls` command lists the files from all the local neeto repos.

```sh
# List all the files in the root directory of neeto repos
neetob local ls --apps "neeto-*-web"

# List files in a specific directory with `--dir` option
neetob local ls --dir public --apps "neeto-*-web"

# List files in a nested directory
neetob local ls --dir app/controllers --apps "neeto-*-web"
```

## Testing

For testing `github` commands use - [neeto-dummy](https://github.com/bigbinary/neeto-dummy) repo.

For testing `heroku` commands use - [neeto-dummy](https://dashboard.heroku.com/apps/neeto-dummy) app.

**Note:** Contact your respective Team Lead if you don't have access.