Allow attaching documentation to environment variables

docs

#1

DESCRIPTION

This enhancement request asks for adding a new column to the project environment variables settings, “Notes” or “Documentation”, and handling Markdown in that field. This would allow to attach documentation for each environment variable configured via the CircleCI Web console.

CircleCI allows to associate environment variables with an app via the app settings > Build Settings > Environment Variables page (URL like: https://circleci.com/gh/$ORG/$APP/edit#build-environment).

Currently, one can set only name and value, equivalent to export NAME=VALUE. But a little configuration setting often has a big impact: Everyone viewing the configuration would benefit from having documentation at the site where they’re reading and editing it. This is already best practice in configuration files, and it would be ideal to be able to follow this practice when configuring the project via CircleCI, as well.

STEPS TO REPRODUCE

  1. Visit app builds page on CircleCI
  2. Hit “Project Settings” link in upper right
  3. Select “Environment Variables” from the second column on the left
  4. Wonder what the allowable values for an environment variable are, or where the value came from and why it might change.

EXPECTED BEHAVIOR

  1. Your team has answered those questions in the Documentation column in the PartCycle environment variables page.

ACTUAL BEHAVIOR

  1. There is no documentation column.
  2. Guess which location your team has documented that stuff under, if they have. README? GitHub project wiki? Basecamp? Shadow config file? Something under docs/*?

REGRESSION

N/A

NOTES

Allowing to document config choices, especially if the doc section had a default template, would guide people to fall into the “pit of success” in adding and editing environment variables.

It appears you cannot currently edit a variable, only delete; having to reenter the documentation each time you edit a variable would be undesirable, so some way to edit rows might be necessitated to make adding and editing documentation practicable.


#2