Last active
June 10, 2016 18:22
-
-
Save parhamr/6e072bc3a75d6e5bc2f49369c9ca41fa to your computer and use it in GitHub Desktop.
Revisions
-
Reid Parham revised this gist
Jun 10, 2016 . 1 changed file with 0 additions and 4 deletions.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -26,10 +26,6 @@ This document contains epics and their stories to identify engineering needs tha NOTE: see additional user stories for details on each of the above sections; consider using a “docs” directory as needed to split longer sections off from the main README file ### As an engineer, I want to install application dependencies with simple, clear instructions 1. Given I have permissions to view the application source code 2. When I view its README file -
Jun 10, 2016 . 1 changed file with 132 additions and 117 deletions.There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -1,134 +1,149 @@ # Development Environment User Stories Boilerplate Features and Behaviors For Engineering Needs. This document contains epics and their stories to identify engineering needs that should be satisfied by application development efforts. It is written for systems engineers and uses the perspectives of software, front end, and user experience engineers. ## Epic: As an engineer, I can build a new development environment ### As an engineer, I want to read a guide to familiarize myself with an application 1. Given I have permissions to view the application source code 2. When I view its README file 3. Then I should see a table of contents with at least these sections: * Development Cluster Reference * Maintenance * Testing * Errors and Failures * Deployment * Automation * Monitoring * Backups * Operations * See Also 4. And I can become familiar with and confident about this application by reading adequate and up to date details and sub-sections of the above NOTE: see additional user stories for details on each of the above sections; consider using a “docs” directory as needed to split longer sections off from the main README file Examples: * https://github.com/copious/nau_store * https://github.com/copious/Zumiez.com ### As an engineer, I want to install application dependencies with simple, clear instructions 1. Given I have permissions to view the application source code 2. When I view its README file 3. Then I should see a “Development Cluster Reference” section that contains the following… * Requirements for installation, including system resources and how long the setup process takes * Lists of packages and versions to install on various flavors of Unixes (with platform specific instructions) * Commands to run for automated build tools and to control services * Scrollback examples for successful and erroneous outcomes * Steps to validate the installation and configurations * Where to find and download database dumps, plus how to import them * Where to find and download media assets * Lists of common errors and how to resolve them * Environment configuration steps and behavior overrides 4. And I am able to bootstrap and maintain my own development environment 5. And I update information as appropriate when I modify the repository or when I find information to be inaccurate or outdated Examples: * https://github.com/sstephenson/rbenv ### As an engineer, I want a diagnostic tool that tells me if anything on my systems is not correctly installed and configured 1. Given I have set up a development environment from README instructions 2. When I run a diagnostic test command 3. Then I should see a list of findings for at least the following… * Filesystem permissions that are too strict or too permissive * Warnings for inadequate system resources * Outdated dependencies daemon and library versions * Configuration values * Necessary authentication privileges * Application-specific concerns 4. And I should have informational resources explaining actions to take or where to find more information Examples: * `$ brew doctor` * `$ composer diagnose` ### As an engineer, I want convenient authentication and authorization for using the application’s integrations (API keys, auth tokens, hosts files, SSH configs) 1. Given I have permissions to view the application source code 2. When I view its README file 3. Then I should see details for the following… * Storage locations, service names, and the navigation paths for shared authentication credentials (e.g. “Lastpass > Notes > Shared > Name”) * Links to information explaining how to generate and manage authentication ephemera * Files providing network addresses, port numbers, and related configuration values for authenticating against remote systems Examples: * https://help.github.com/articles/generating-ssh-keys/ * https://developer.github.com/guides/using-ssh-agent-forwarding/ ## Epic: As an engineer, I can fully rebuild an existing development environment Notes: also remove local caches, options to re-apply the run-once routines, ## Epic: As an engineer, I can maintain my development environment Notes: import data/assets from environments (see also: automated DB dumps), export data/assets to environments, compile assets, diagnose problems, automated health/status checks, apply patches/upgrades, who do I ask for help?, check logs from production, logrotate ## Epic: As an engineer, I can maintain and improve applications using my development environment Notes: dispatch tests, auth forwarding, location allow/deny, robots, sitemap, route requests to admin, review log files, trace errors, cron/background visibility, dependency management tools, packages and dotfiles for virtual machines, ### As a systems engineer, I want my peers to understand the systems I maintain 1. Given I have created a new feature or modified an existing behavior 2. When I submit the changes to a repository for peer review 3. Then I write new and/or update existing documentation in README and relevant files 4. And I use proper grammar, syntax, formatting, and examples of commands 5. And my engineering peers are able to follow my instructions and know what to do if errors or issues occur ### As a software engineer, I want my development environment to match production as closely as possible, so that I have confidence in its behaviors 1. Given I have a development environment for a codebase 2. When I add features or maintain existing behaviors 3. Then I run tests and interact with the applications 4. And my environment is similar to production (or easily re-configured) for the following behaviors… * Caching layers * HTTPS implementation * Cross-Origin Resource Sharing (CORS) headers ### As a systems engineer, I want each environment isolated, so that accidental data loss does not occur 1. Given I am a maintainer of development environment tooling 2. When I add or modify application dependencies like APIs, services, data sources, backups, asset storage, et cetera 3. Then I ensure the configurations are environment-aware with namespaces, environment values, filesystem flags, software sub-classes, or similar constructs 4. And my CRUD actions performed in an environment only affect that environment 5. And my automated routines for one environment never interferes with other environments 6. And my features include relevant, text-based outputs of the current environment’s name for clarity Examples: * Subject lines of automated emails include the URL or environment name * Configuration files with environment names as the keys (e.g. the Rails conventions) * Webpage headers with environment-specific overlays when not in production * Proscriptive robots.txt files to prevent indexing of non-production systems * Functional testing where features and contexts can use caching when flagged ### As a software engineer, I want access to production diagnostics, so that I may be more effective at debugging problems 1. Given I have a report of a behavior seen in production 2. When I try to reproduce the behavior and understand why it occurs 3. Then I should be able to obtain privileged diagnostic information 4. And I can consult the application’s README for whom to contact, where to look, which services to use, and relevant commands to use 5. And I should be provided the necessary authentications and authorizations that comply with best practices 6. And I should be able to view, search, download, or transfer the following ephemera… * Log entries from the application stack (webserver daemon, dispatch daemon, application, framework, etc) * Error messages, stack traces, and runtime conditions for errors * Event timings for automated, background operations * Reports specific to the problem domain, application integrations, and business operations 7. And I am able to effectively debug the reported behaviors Examples: * Authentication forwarding instructions * Public interfaces for Zabbix and Nagios * New Relic error traces * Centralized logging tools -
Apr 2, 2016 .There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode charactersOriginal file line number Diff line number Diff line change @@ -0,0 +1,134 @@ Development Environment User Stories Skip to end of metadata Created by Reid Parham, last modified on Jan 07, 2015 Go to start of metadata Boilerplate Features and Behaviors For Engineering Needs. This document contains epics and their stories to identify engineering needs that should be satisfied by application development efforts. It is written for systems engineers and uses the perspectives of software, front end, and user experience engineers. 1 Boilerplate Features and Behaviors For Engineering Needs. 2 Epic: As an engineer, I can build a new development environment 2.1 As an engineer, I want to read a guide to familiarize myself with an application 2.2 As an engineer, I want to install application dependencies with simple, clear instructions 2.3 As an engineer, I want a diagnostic tool that tells me if anything on my systems is not correctly installed and configured 2.4 As an engineer, I want convenient authentication and authorization for using the application’s integrations 3 Epic: As an engineer, I can fully rebuild an existing development environment 4 Epic: As an engineer, I can maintain my development environment 5 Epic: As an engineer, I can maintain and improve applications using my development environment 5.1 As a systems engineer, I want my peers to understand the systems I maintain 5.2 As a software engineer, I want my development environment to match production as closely as possible, so that I have confidence in its behaviors 5.3 As a systems engineer, I want each environment isolated, so that accidental data loss does not occur 5.4 As a software engineer, I want access to production diagnostics, so that I may be more effective at debugging problems Epic: As an engineer, I can build a new development environment As an engineer, I want to read a guide to familiarize myself with an application Given I have permissions to view the application source code When I view its README file Then I should see a table of contents with at least these sections: Development Cluster Reference Maintenance Testing Errors and Failures Deployment Automation Monitoring Backups Operations See Also And I can become familiar with and confident about this application by reading adequate and up to date details and sub-sections of the above NOTE: see additional user stories for details on each of the above sections; consider using a “docs” directory as needed to split longer sections off from the main README file Examples: https://github.com/copious/nau_store https://github.com/copious/Zumiez.com As an engineer, I want to install application dependencies with simple, clear instructions Given I have permissions to view the application source code When I view its README file Then I should see a “Development Cluster Reference” section that contains the following… Requirements for installation, including system resources and how long the setup process takes Lists of packages and versions to install on various flavors of Unixes (with platform specific instructions) Commands to run for automated build tools and to control services Scrollback examples for successful and erroneous outcomes Steps to validate the installation and configurations Where to find and download database dumps, plus how to import them Where to find and download media assets Lists of common errors and how to resolve them Environment configuration steps and behavior overrides And I am able to bootstrap and maintain my own development environment And I update information as appropriate when I modify the repository or when I find information to be inaccurate or outdated Examples: https://github.com/sstephenson/rbenv As an engineer, I want a diagnostic tool that tells me if anything on my systems is not correctly installed and configured Given I have set up a development environment from README instructions When I run a diagnostic test command Then I should see a list of findings for at least the following… Filesystem permissions that are too strict or too permissive Warnings for inadequate system resources Outdated dependencies daemon and library versions Configuration values Necessary authentication privileges Application-specific concerns And I should have informational resources explaining actions to take or where to find more information Examples: $ brew doctor $ composer diagnose As an engineer, I want convenient authentication and authorization for using the application’s integrations (API keys, auth tokens, hosts files, SSH configs) Given I have permissions to view the application source code When I view its README file Then I should see details for the following… Storage locations, service names, and the navigation paths for shared authentication credentials (e.g. “Lastpass > Notes > Shared-Copious > Name”) Links to information explaining how to generate and manage authentication ephemera Files providing network addresses, port numbers, and related configuration values for authenticating against remote systems Examples: https://help.github.com/articles/generating-ssh-keys/ https://developer.github.com/guides/using-ssh-agent-forwarding/ Epic: As an engineer, I can fully rebuild an existing development environment Notes: also remove local caches, options to re-apply the run-once routines, Epic: As an engineer, I can maintain my development environment Notes: import data/assets from environments (see also: automated DB dumps), export data/assets to environments, compile assets, diagnose problems, automated health/status checks, apply patches/upgrades, who do I ask for help?, check logs from production, logrotate Epic: As an engineer, I can maintain and improve applications using my development environment Notes: dispatch tests, auth forwarding, location allow/deny, robots, sitemap, route requests to admin, review log files, trace errors, cron/background visibility, dependency management tools, packages and dotfiles for virtual machines, As a systems engineer, I want my peers to understand the systems I maintain Given I have created a new feature or modified an existing behavior When I submit the changes to a repository for peer review Then I write new and/or update existing documentation in README and relevant files And I use proper grammar, syntax, formatting, and examples of commands And my engineering peers are able to follow my instructions and know what to do if errors or issues occur As a software engineer, I want my development environment to match production as closely as possible, so that I have confidence in its behaviors Given I have a development environment for a codebase When I add features or maintain existing behaviors Then I run tests and interact with the applications And my environment is similar to production (or easily re-configured) for the following behaviors… Caching layers HTTPS implementation Cross-Origin Resource Sharing (CORS) headers As a systems engineer, I want each environment isolated, so that accidental data loss does not occur Given I am a maintainer of development environment tooling When I add or modify application dependencies like APIs, services, data sources, backups, asset storage, et cetera Then I ensure the configurations are environment-aware with namespaces, environment values, filesystem flags, software sub-classes, or similar constructs And my CRUD actions performed in an environment only affect that environment And my automated routines for one environment never interferes with other environments And my features include relevant, text-based outputs of the current environment’s name for clarity Examples: Subject lines of automated emails include the URL or environment name Configuration files with environment names as the keys (e.g. the Rails conventions) Webpage headers with environment-specific overlays when not in production Proscriptive robots.txt files to prevent indexing of non-production systems Functional testing where features and contexts can use caching when flagged As a software engineer, I want access to production diagnostics, so that I may be more effective at debugging problems Given I have a report of a behavior seen in production When I try to reproduce the behavior and understand why it occurs Then I should be able to obtain privileged diagnostic information And I can consult the application’s README for whom to contact, where to look, which services to use, and relevant commands to use And I should be provided the necessary authentications and authorizations that comply with best practices And I should be able to view, search, download, or transfer the following ephemera… Log entries from the application stack (webserver daemon, dispatch daemon, application, framework, etc) Error messages, stack traces, and runtime conditions for errors Event timings for automated, background operations Reports specific to the problem domain, application integrations, and business operations And I am able to effectively debug the reported behaviors Examples: Authentication forwarding instructions Public interfaces for Zabbix and Nagios New Relic error traces Centralized logging tools
Reid Parham
revised
this gist