terminus-plugin-project / terminus-dibs-plugin
Dibs - A Terminus plugin that allows you to call dibs on your Pantheon environments.
Installs: 15 933
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 5
Forks: 1
Open Issues: 1
Type:terminus-plugin
This package is auto-updated.
Last update: 2024-10-28 14:43:28 UTC
README
Dibs is a Terminus plugin for "calling dibs" on site environments. It can be useful for teams who are working together on a limited number of multidevs, or in the context of build automation and continuous integration.
Installation
The simplest way to install this plugin is via Composer! Run the following command to install this plugin:
composer create-project --stability=beta -d ~/.terminus/plugins/ terminus-plugin-project/terminus-dibs-plugin:~1
If you do not wish to use Composer, place the contents of this repository into
~/.terminus/plugins/dibs
or the location of your $TERMINUS_PLUGINS_DIR
. You
may do so either by cloning this repository using git, or by un-compressing the
tarball from a release on GitHub.
Verify that installation succeeded by running terminus help env:dibs
Usage
Dibs'ing a specific environment
To call dibs on the dev
environment on a site called your-site
run:
terminus env:dibs your-site.dev "Need the dev environment for a thing."
If the call succeeded, you should see a message like the following:
[notice] Called dibs on the dev environment.
...In addition to details about the environment.
Note that you must leave a note when calling dibs. If you or anyone else on your
team attempt to call dibs on dev
again, you'll see an error containing the
message originally used to call dibs. Be sure to leave meaningful notes for your
colleagues!
Un-dibs'ing an environment
Once you're done using your environment, you can undibs it by running the following command:
terminus env:undibs your-site.env
If the call succeeded, you should see a message like the following:
[notice] Undibs'd the dev environment.
...In addition to details about the environment.
Afterward, you or anyone else on your team may call dibs on dev
again.
Dibs'ing any available environment
If you don't care which environment you call, you may run the following command, which doesn't require an environment name. Dibs will attempt to find an environment that hasn't already been called.
terminus site:dibs your-site "Testing some layout tweaks"
If an environment was found, you'll see the same success message as shown above, including the name of the dibs'd environment. Additionally, details about the dibs'd environment will be returned.
If all environments are spoken for, you'll see an error message
[error] Unable to find an environment to dibs.
By default, all environments except for the live environment may be dibs'd.
Dibs'ing an environment based on a filter
If you'd like to dibs an environment, but wish to limit the environments made available for dibs'ing, you can do so by providing a regex pattern as a filter.
terminus site:dibs your-site "Experiments" '^((?!^(dev|test|live)$).)*$'
The above command would call dibs on a multidev, ignoring the dev
, test
, and
live
environments.
Note: In both cases where no specific environment is provided, only those environments that are fully spun-up are dibs'able. If you need to dibs an environment as it is being spun up, specify the environment name.
Dibs Report
If you want to see an overview of environments and their dibs status, you can get an environment-by-environment breakdown using the following command:
terminus site:dibs:report your-site
Doing so, you'd get a response like this:
------------- ---------------- ---------- ------------------------ --------------------------
Environment Status By At Message
------------- ---------------- ---------- ------------------------ --------------------------
dev Available
test Not Ready
multidev-1 Already called username Thu Nov 3rd at 07:23pm New feature for the boss
------------- ---------------- ---------- ------------------------ --------------------------
Note that you can also supply a regex filter to limit the environments returned in the report:
terminus site:dibs:report your-site '^((?!^(dev|test|live)$).)*$'
You can also use a flag, --older-than
, to further filter down environments that have been dibs'd for a given amount of time (in seconds):
terminus site:dibs:report your-site '^((?!^(dev|test|live)$).)*$' --older-than=1800
Use-cases
This plugin assumes that you have persistent or semi-persistent environments spun up on your Pantheon site. It can be useful for a variety of use-cases, both human and automated.
Poor man's multidev
Suppose you have a team of two or more and you're working for a client who is
too stingy for multidevs. If two of you want to try out new configurations in
the same area of the site, how do you figure out who uses dev
vs. test
?
This plugin can help manage work!
terminus env:dibs your-site.test "New features for the boss"
Speed up CI builds
Suppose you run automated tests on a CI server that spin up and tear down multidev environments, but the database is so large that a site create takes forever.
Use this plugin to speed up your builds! Keep a handful of persistent CI
environments around, named using a convention like ci1
, ci2
, etc. Instead of
spinning up/tearing down environments, just call dibs!
export PENV=`terminus site:dibs --field=id -- your-site "Using env for build." '^ci\d$'`
Note you can also specify multiple fields (--fields=id,domain
) (rather than
one) or specify an alternative format (--format=json
) if desired. For more
details, run: terminus help site:dibs
Multidev management
Suppose you have a large team or a large number of features you're working on simultaneously, but only a handful of multidev environments.
Use this plugin to keep everyone from stepping on each other's toes! Keep your
multidev count at max capacity, named using a convention like dev1
, dev2
,
etc. Call dibs on an environment before you start working on a feature or as
soon as it's ready for QA.
terminus site:dibs your-site "Feature name/number" '^dev\d+$'
Internals
In order to maintain state about whether or not an environment is dibs'd, this
plugin writes a small JSON file to a publicly accessible location in the site
environment's file system. If you run any file-based workflow operations (like
cloning from live
to your dibs'd environment), dibs state will be lost.
This plugin is smart enough to recognize when an environment has been created
from a previously dibs'd environment (e.g. a clone of db/files from one
environment to another), and will allow the target site to be dibs'd (like if
dev
was already dib's and you spun up multidev-1
from dev
, even though the
dibs JSON from dev
would exist on multidev-1
, this plugin will still allow
you to call dibs on multidev-1
anyway).
Notes
- Compatibility with
terminus 2.0.x
:- 1.x versions of Dibs is compatible with
1.x
up to2.0.0
versions of Terminus.
- 1.x versions of Dibs is compatible with