Engineering Playbook
Purpose
Within Truss we have much experience of and opinions regarding engineering tools, processes, and practices. The problems and choices that we encounter in our day-to-day practice are rarely new. Having a straightforward way of applying the things we collectively know to the problems we face would be a source of great efficiency for us.
This collection of documents is intended to be simple and searchable, each one containing the essence of Truss opinions on a particular topic. Whilst any Trussel is free to edit these documents, there is some expectation that these are to be curated by the broad engineering community at Truss. To that end, proposed changes should be submitted via a PR and SMEs will be identified to act as curators for particular areas of knowledge.
We build and deploy these docs using Docusaurus, a React-based static site generator, and GitHub Pages.
Layout
/docs/
contains all of our documentation files (in markdown). If you are here to edit or peruse the docs, this is where you want to go./src/
contains our React components and pages. Currently, this only contains our main page. It will be rare to need to be in this folder./static/
contains all of our images and other static files. If you want to add a screenshot or other visual to your doc page, you will need to upload it to this folder./sidebars.js
contains the sidebars for our doc folders. We autogenerate our sidebars in order to minimize how often our JavaScript files need to be updated. It is unlikely that you will need to update this file directly.
Contents
- ATOs & Risk Management Framework - A high level overview of Federal compliance requirements.
- Developer Tools & Practice - Opinions and resources relating to the tools we use to do our work.
- Documentation - How to write effective documentation your users will read.
- Web Development - Languages, frameworks and tools used to develop web applications
- InfraSec - Infrastructure and security are foundational disciplines for building and maintaining stable systems.
- Leadership - Guidance and resources around being an Engineering Lead or Manager at Truss.
- Templates - "Ooh, ooh... I have a thing to add." Here's how to add to this Playbook.
- Practices - Resources on how the Truss Engineering practices organize.
Initial Setup (on MacOS)
Clone the repo
-
Open your terminal/command line.
-
Clone the repo onto your machine and
cd
into it:git clone https://github.com/trussworks/Engineering-Playbook.git && cd Engineering-Playbook
Install Dependencies
Choose one of the following methods to install the dependencies.
Manually
brew update
brew install nodenv
brew install yarn
brew install pre-commit
pre-commit install
fresh-brew
With bash <(curl -s https://raw.githubusercontent.com/trussworks/fresh-brew/main/fresh-press)
If you're using the Fish shell, run this command instead:
bash (curl -s https://raw.githubusercontent.com/trussworks/fresh-brew/main/fresh-press | psub)
This command will install Homebrew if you don't already have it, or update it
if you already have it. It will also install or update git
and the GitHub CLI,
as well as the dependencies that are specific to this project, as defined in
fresh-brew.local
and Brewfile.local
. Finally, it will launch the MilMove docs
website for you. Read more about the script by visiting the repo:
trussworks/fresh-brew.
If the script fails, pay attention to any errors or warnings from Homebrew in the terminal. Homebrew usually provides detailed instructions for fixing things, so read them carefully and follow their instructions. For example, a common issue is missing or outdated Command Line Tools. The message looks like this:
Warning: A newer Command Line Tools release is available.
Update them from Software Update in System Preferences or run:
softwareupdate --all --install --force
If that doesn't show you any updates, run:
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install
Alternatively, manually download them from:
https://developer.apple.com/download/more/.
If you see this, follow the instructions, then quit and restart your terminal once the Command Line Tools are installed, and run the setup script above again.
With Nix
- Install or update Homebrew using the same script as in the previous section,
but without running the
*.local
scripts:
export SKIP_LOCAL=true
bash <(curl -s https://raw.githubusercontent.com/trussworks/fresh-brew/main/fresh-press)
For Fish shell:
export SKIP_LOCAL=true
bash (curl -s https://raw.githubusercontent.com/trussworks/fresh-brew/main/fresh-press | psub)
- Install Nix if you don't already have it:
sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume --no-daemon
Note: if you're using the Fish shell, you'll need to complete an extra step.
- Quit and restart your terminal
- Run
direnv allow
- Run
nix/update.sh
Run the server
npm install
npm start
The site should load automatically in your browser at http://localhost:4000/Engineering-Playbook/.
If you would like to enable the local search, use the production build instead:
npm run build
npm run serve
Deployment
This site is currently deployed using GitHub pages: https://trussworks.github.io/Engineering-Playbook/. We're using GitHub actions to redeploy whenever changes are merged to the main branch, which includes all commits that are made and saved directly in GitHub.
Be aware that GitHub pages has a soft limit of 10 deploys per hour, and it is possible we could run up against this (read more about the limitations of pages here: About GitHub Pages). It should not have a significant affect on our day-to-day activities, however, and may never become a noticeable issue.
Licenses
This project uses two licenses. One is for the software components written by
TrussWorks, such as but not limited to plugins, modifications, and scripts to
integrate and deliver the Docusaurus repository. This license the is the
Apache-2.0 license. The other license is for non-software components such as
documentation which mostly reside in the docs/
directory. This license is the
CCA-4.0 license.
Apache License, Version 2.0
This license covers the software components of this project and not the documentation (non-software) components of this project.
This license only references software components written by TrussWorks, LLC to customize or modify the Docusaurus documentation framework. A list of software components that fall under this license will be referenced in this file by file path.
Creative Commons Attribution 4.0 International Public License
This license covers the documentation (non-software) components of this project and not the software components of this project.
The non-software components of this project mostly exist in the docs/
directory but include other documentation files within the repository. A list of
non-software components outside of the docs/
directory will be referenced in
this file by file path.
- ./README.md
- ./CODE_OF_CONDUCT.md
- ./CONTRIBUTING.md