Using Bento individually and on team projects

With Bento release 0.8, we’ve tuned its default behavior for individual use, rather than something that requires team-wide adoption. This post describes our learnings from user feedback and how to configure Bento for team use.

New Bento behavior

Release 0.8 changes Bento’s out-of-the-box behavior. In user research interviews and GitHub issues over the past month we’ve consistently heard that Bento’s file footprint and modification of Git state made it challenging to adopt. v0.8 emphasizes an incremental and personal, rather than team-wide, workflow that’s makes Bento a smaller commitment to use:

1. Other project contributors won’t see Bento files or have their workflows changed. It’s just for you.

2. You no longer need to manually run Bento. After initialization Bento will automatically check for issues in your code as you commit, analyzing only the files that have changed.

3. You won’t see a project’s tech debt during initialization. It’s still there for you though when you’re ready to take a peek and tackle it with your team.

Individual Use

By default Bento configures itself for personal use when bento init runs. This means that it:

• automatically checks for issues introduced by your code, as you commit it

• only affects you; it won’t change anything for other project contributors or modify Git state

By default Bento analyzes code that you commit, not an entire project’s codebase.

You can always manually run Bento on files or directories with staged changes (i.e., those listed using git status) via:

$ bento check

To check specific staged files or directories run:

$ bento check [PATHS]

Analyze an entire project and display all results that aren’t in the archive file (~/.bento/archive.json) with:

$ bento check --all

Autorun

Initialization enables the autorun command, through which Bento blocks commits if Bento returns results. To make it non-blocking run:

$ bento enable autorun --no-block

The autorun feature uses Git hooks and replaces the command bento install-hook. If the hook incorrectly blocks your commit, you can skip it by passing the --no-verify flag to Git at commit-time (please use this sparingly since all hooks will be skipped):

$ git commit --no-verify

Team Use

To setup Bento for all project contributors, add Bento’s configuration to Git (it’s ignored by default):

$ cd <PROJECT DIRECTORY>
$ git add --force .bento .bentoignore

Contributors can run Bento for themselves using the project’s configuration via:

$ pip3 install bento-cli && bento init

Bento files

Some configuration files moved from per-project locations to a single global folder, ~/.bento/. This reduces Bento’s footprint, leaving only project-specific files in their respective directories, and it simplifies future Bento updates. Also, a few files have been renamed.

Global artifacts now in ~/.bento/:

• ~/.bento/config.yml: Bento’s global configuration file

• ~/.bento/last.log: debug log for the last invocation of bento check

• ~/.bento/venv/: a directory containing virtual environments in which individual Bento tools run

• ~/.bento/archive.json: created when you first run bento archive, this is Bento’s record of archived findings, i.e., your tech debt, or your project’s tech debt if you configure Bento to analyze your whole project and have archived issues;

Artifacts in per-project directories in which Bento has been initialized:

• .bento/config.yml: project-specific Bento configuration that defines tools and checks enabled for the project

• .bentoignore: files and paths listed here will be ignored (this is Bento’s equivalent to .gitignore)

Running Bento in CI/CD

When in CI, Bento analyzes your entire project, not just the latest commit. So that you don’t have to fix all existing issues before making Bento blocking, its archive feature allows historical issues to be tracked and ignored during CI. To use the archive feature so Bento returns a non-zero exit code only for new issues, rather than all existing issues, first create the archive:

$ cd <PROJECT DIRECTORY>
$ bento archive .

Then commit Bento’s configuration to the project:

$ git add -b-force .bento .bentoignore

You can then add Bento to your CI scripts:

$ pip3 install bento-cli && bento --version
$ bento --agree --email=<YOUR_EMAIL> check --all 2>&1 | cat

For CircleCI the above commands become:

version: 2.1

jobs:
  bentoCheck:
  executor: circleci/python:3.7.4-stretch-node
  steps:
    - checkout
    - run:
        name: "Install Bento"
        command: pip3 install bento-cli && bento --version
    - run:
        name: "Run Bento check"
        command: bento --agree --email=<YOUR_EMAIL> check --all 2>&1 | cat

bento check will return a non-zero exit code if it finds issues in your code.

We’d love to hear your feedback about Bento 0.8 and specifically these workflow changes. Don’t hesitate to reach out to us at support@r2c.dev or on Slack. We also welcome GitHub issues, too!