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.
- 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
- 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:
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 > 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/
Notes: also remove local caches, options to re-apply the run-once routines,
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
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,
- 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