Skip to content

Instantly share code, notes, and snippets.

@bsommardahl

bsommardahl/ideal_starting.md

Last active May 7, 2019 14:20
Show Gist options
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save bsommardahl/c2d57d51242b2336b7876f20fcf16ac6 to your computer and use it in GitHub Desktop.
Save bsommardahl/c2d57d51242b2336b7876f20fcf16ac6 to your computer and use it in GitHub Desktop.
Download ZIP
Ideal Starting Point for Acklen Avenue Projects
Raw
ideal_starting.md

What would be the ideal starting point for any Acklen Avenue software project?

Developer's Coding Environment

  • Wallaby.js working for all popular editors
  • Live debug set up in all popular editors (those that can debug, that is)
  • Works in Windows, OSX and Linux.

Boilerplate

  • Frontend is architected to be a large application.
  • Backend is architected to be a large application.
  • API endpoints for health check on all API's (ex: /status)
  • Display build version and environment in browser console.
  • Backend error stack traces visible in 500 responses (dev only)
  • Functionality to create, read, update and delete at least one "widget" (proves db access).
  • Front-end and back-end logging to a cloud logging service (ex: Loggly)
  • Build scripts for...
    • build/transpile/compile/whatever
    • linter
    • starting application
    • run unit tests
    • run acceptance tests
    • watch (development workflow)
  • Feature toggling set up (applied to widget functionality)
  • API documentation automatically generated (ex: swagger)
  • API's work with JWT
  • Auth0/Other IDP working in front-end
  • IDP in a separate service or server (ex: Auth0, Okla, custom)
  • Db migrations can build the database from zero with one command
  • Full stack in docker compose

Testing

  • At least one happy path example UI test per scenario (marked critical, using in-memory db)
  • At least example API test per scenario (using in-memory db)
  • Cucumber features working from npm script.
  • Example AAT's passing for all domain-related scenarios
  • Ability to turn on/off verified fakes with env var
  • Example verified fakes and contract tests for at least repository
  • AAT's can be run from hiptest (or whatever test tracking platform we're using)
  • Feature files available in project wiki
  • 100% unit test coverage over non-bootstrapping code (including examples of test double usage).

Ops/CI/CD

  • Adheres to https://12factor.net/
  • Each piece in a docker container.
  • Infrastructure in yaml files for Cloud Formation or Terraform (instead of extensive use of bash)
  • Project builds in CI
  • Environment per branch working in CI/CD
  • Staging env builds from staging branch and can run in client or Acklen AWS account
  • Prod env builds from master branch and can run in client account
  • Build instructions for Gitlab and Buildkite
  • Databases in docker containers, volumes in static location for persistence
  • Can build and run entire stack inside CI and run AAT's against the stack before deploying to any AWS environment.
  • We can deploy to Azure, Google Compute, AWS and the client's data center with similar effort.
  • CI/CD should be the same effort no matter what docker container backend (Ruby, NodeJs, Dotnet Core, Mickey Mouse) - Language-Agnostic CI/CD.
  • Containers must be stateless: the application can only store state in external stores (like databases, queues, memory caches). This ensures that we can run multiple instances at the same time and scale them out horizontally as needed.
  • Containers must get config from environment variables: environment-dependent variables (like credentials) should not be hardcoded in the code.
  • Containers must be expose its status: when healthy, the application is ready to accept requests or handle other kinds of loads.
  • Containers must gracefully shutdown on termination signal: to archieve zero-downtime, the application has to finish all in-progress work, like responding to in-flight requests, before exiting.
  • Containers must handle errors gracefully: perfect software doesn’t exist. One needs to make sure that any errors are caught and log them before termination.
  • Containers must use a structured logger: it’s easier to query and process structured data.
  • Containers must expose application metrics: it helps when one needs to monitor the state of running applications.

Help

  • Walkthrough video(s) explaining how the boilerplate works
  • Ramp-up steps documented in project README.md so that QA can run project locally without dev help.
  • Documentation for how to implemennt Command, CommandValidators,Command Handlers, AggregateRoot, Events, EventHandlres, and Repositories with TDD. (maybe a video)
  • Video of "How to implement a Create Command from nothing to a real case"
  • Video of "How to deliver a Create/Update/Delete Command from the user story to real code"
  • Video of "How to deliver add a Query from nothing the user story to real code using the Repository Pattern"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment