Skip to content
This repository has been archived by the owner on Mar 12, 2024. It is now read-only.

Latest commit

 

History

History
90 lines (57 loc) · 3.99 KB

RFC.md

File metadata and controls

90 lines (57 loc) · 3.99 KB
Raw

RFC-001

Doko proposes to build a plugin to assist web developers determine which environment they are accessing on a particular browser tab, along with some relevant meta information by inspecting a series of HTML meta tags defined by the Doko protocol.

The aim is to develop a rather elegant and simple solution for developers and testers.

Motivation

Whilst past approaches have included stylising user interfaces with alternate colour schemes or overlay banners to denote the environment, it does not solve presenting meta relevant meta data to the developer or tester.

This approach is particularly troublesome when building public facing web sites e.g marketing sites, e-Commerce implementations.

Doko's approach abstracts this information using meta tags and leaves the plugin to deliver a developer friendly overlay without changing the asthetics of the application's user interface.

The team at Anomaly often collaborate with other software development houses. Changing their process of user interface development can prove to be challenging. Doko's proposes a non-breaking mechanism to achieve

The Doko Protocol

The Doko protocol is inspired by standards like The Open Graph protocol to describe the meta data, required by the plugin. This is broadly classified into the following sections:

  • Environment - containing directives for the environment being accessed
  • Abstract - defines information displayed as an abstract
  • Facts - facts are an unlimited set of facts about the deployment (Doko promotes a sensible limit of five objects in the interest of better user experience).
  • Feedback - provides a mechanism to provide quick link backs to ticket systems like (but not limited to) Github issues.

Environment

Tells Doko about the environment it's look at, this determines the badge presented to the user.

content must contain either:

  • production - for production deployments, typically crucial
  • staging - for Staging / QA deployments typically handled by a CI/CD process
  • development - for development environments typically a developer's local machine.

Example:

<meta name="doko:environment" content="production"/>

Abstract

An abstract is a strictly defined section that provides the user the minimum amount of context of the environment. It allows you to provide a title and a subtitle - the content can be determined by the application, and should be limited to a 30 characters.

Example:

<meta name="doko:title" content="Anomaly Software"/>
<meta name="doko:subtitle" content="https://anomaly.netlifyapp.com"/>

Facts

Facts are a key, value pairs that are displayed by the plugin in the expanded state. You may provide as many facts as you feel relevant for your application. However it's considered best practice to limit it to five.

Example:

<meta name="doko:fact" content="Server|Netlify"/>
<meta name="doko:fact" content="Database|PostgreSQL 2.0"/>
<meta name="doko:fact" content="Node|ap-01a"/>

Feedback

This section is reserved to provide links to feedback systems like issue trackers.

Example:

<meta name="doko:postissue" content="https://github.com/anomaly/anomaly/issues/new"/>

Doko proposes to develop this further in the future to include in plugin integration with selected services.

Plugin Behaviour

The proposed widget will have three states:

  • Condensed - displaying a badge only
  • Abstract - displaying a badge, and the abstract
  • Expanded - displaying all content proposed by the protocol

Interactions:

  • Clicking the badge toggles between the condensed and abstract views
  • The abstract view reveals a chevron that allows the user to expand and contract between the abstract and expanded views
  • At any stage clicking the badge toggles it back to the condensed view
  • Clicking the "Open an Issue" link will open a new issue in the designated hosted issue tracker
  • the production, staging, development keywords determine the badge that's displayed in the widget