...
 
Commits (6)
## 18F Development Guide
## 18F Engineering Practices
A set of guidelines and best practices for an awesome engineering team
18F promotes team best practices across specialty areas through guilds. These guilds support their members in whatever way deemed most appropriate by those members themselves.
* [Third-Party Integrations](/integrations)
* [Workflow Best Practices](/workflow)
* [Project Setup](/project_setup)
* [Architecture Reviews](/architecture_reviews)
* [Accessibility Scanning Guide](/accessibility_scanning)
* [People Guidance](/people)
* [Continuous Deployment with Autopilot Guide](/continuous_deployment)
* [Datastore Selection Guidance](/datastore_selection)
This repo is where the Engineering Practices Guild keeps its guide to best practices and resources for software development.
### Language Guides
### Quicklinks
* [Language Selection Guidance](/language_selection)
* [Node](/nodejs)
* [Python](/python)
* [Ruby](/ruby)
- Guide: https://engineering.18f.gov/
- [CONTRIBUTING.md](CONTRIBUTING.md) on how to build this guide locally and submitting PRs/issues.
### Public domain
## Our mission
We believe that government websites should be functional, maintainable, and thoughtfully designed. Our guild helps TTS promote the adoption and advancement of software development best practices. In this way, TTS can lead by example while providing effective services that help our partners and customers fulfill their missions.
To achieve our vision, the Engineering Practices Guild works to:
- Support the continuous learning necessary for successful software engineering work.
- Provide TTS developers with easy-to-understand, actionable guidance around software engineering best practices.
- Promote a central knowledge base of shared tools and common patterns.
- Create a healthy and supportive internal environment so that we can, in turn, bolster healthy external communities related to our work.
This project is in the worldwide [public domain](LICENSE.md). As stated in
[CONTRIBUTING](CONTRIBUTING.md):
## How to track what we're doing, and how you can be involved!
We use issues in this repo to track work. If you'd like to suggest a new topic or flag an issue, please [file an issue](https://github.com/18F/development-guide/issues/new/).
The software development industry is ever-changing, and our guide is a living document. Please suggest edits or changes via pull request.
## Public domain
This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
> This project is in the public domain within the United States, and copyright
> and related rights in the work worldwide are waived through the [CC0 1.0
......
title: 18F Front-End Guide
title: 18F Engineering Practices Guide
styles:
- /assets/css/styles.css
......@@ -13,6 +13,10 @@ exclude:
theme: uswds-jekyll
include:
- _pages
- .rubocop.yml # in _pages/ruby
defaults:
- scope:
path: ""
......@@ -20,7 +24,11 @@ defaults:
values:
layout: page
permalink: pretty
collections:
pages:
output: true
permalink: /:path
markdown: kramdown
sass:
......@@ -38,10 +46,10 @@ logoalt: 18F logo
google_analytics_ua: UA-48605964-19
repo:
name: Front-End Guide
name: 18F Engineering Practices Guide
description: Main repository
url: https://github.com/18F/frontend
url: https://github.com/18F/development-guide
back_link:
url: "https://guides.18f.gov/"
url: "https://18f.gsa.gov/guides/"
text: Read more 18F Guides
......@@ -8,9 +8,9 @@
usa_banner: true
primary:
# this is a key into _data/navigation.yml
links: primary
#primary:
# # this is a key into _data/navigation.yml
# links: primary
secondary:
# this is a key into _data/navigation.yml
......
# _data/navigation.yml
primary:
- text: CSS
href: /css/
- text: JavaScript
href: /javascript/
- text: Web Components
href: /web-components/
- text: Security
href: /security/
#primary:
# - text: Example
# href: /example/
secondary:
- text: More 18F guides
href: https://guides.18f.gov/
href: https://18f.gsa.gov/guides/
external: true
# TODO: figure out how to nest links
css:
- text: CSS
href: /css/
- text: Architecture
href: /css/architecture/
- text: Documentation
......@@ -39,7 +35,10 @@ css:
- text: Variables
href: /css/variables/
# TODO: figure out how to nest links
js:
- text: JavaScript
href: /javascript/
- text: Dependencies
href: /javascript/dependencies/
- text: Frameworks
......@@ -49,6 +48,11 @@ js:
- text: Style / Linting
href: /javascript/style/
# TODO: figure out how to nest links
security:
- text: Security
href: /security/
- text: Content Security Policy (CSP)
href: /security/content-security-policy/
- text: Output Encoding
href: /security/output_encoding/
---
title: Accessibility Scanning using AccessLint
---
## Accessibility Scanning using AccessLint
[AccessLintCI](https://github.com/accesslint/accesslint-ci) is an automated accessibility scanning tool. It is configured with CircleCI (Travis and Jenkins support pending) to leave comments on Pull Requests stating potential accessibility problems with the committed code.
......
---
title: 'DATA Act Pilot: Simplicity is Key'
---
# DATA Act Pilot: Simplicity is Key
## TL;DR
......
---
title: Architecture Reviews
---
# Architecture Reviews
18F has the pleasure of employing a plethora of truly great software
developers. Unfortunately, our project-focus tends to silo our engineers from
each other. Rather than wait for knowledge to naturally diffuse through team
......
---
title: 'Micro-purchase: Do one thing well'
---
# Micro-purchase: Do one thing well
## TL;DR
......
---
title: Code Review
---
# Code Review
> A friendly guide for reviewing code — and not each other — at 18f.
(Forked from the excellent Consumer Financial Protection Bureau
......
---
title: Continuous Deployment
---
# Continuous Deployment
## Pre-requisites
......
---
title: Architecture
permalink: /css/architecture/
sidenav: css
---
# Architecture
......
---
title: Documentation
permalink: /css/documentation/
sidenav: css
---
# Documentation
......
---
title: Formatting
permalink: /css/formatting/
sidenav: css
---
......
---
title: Frameworks
permalink: /css/frameworks/
sidenav: css
---
# Frameworks
......
---
title: CSS
permalink: /css/
sidenav: css
---
......
---
title: Inheritance
permalink: /css/inheritance/
sidenav: css
---
# Inheritance
......
---
title: Linting
permalink: /css/linting/
sidenav: css
---
# Linting
......
---
title: Naming
permalink: /css/naming/
sidenav: css
---
# Naming
......
---
title: Preprocessors
permalink: /css/preprocessors/
sidenav: css
---
# Preprocessors
......
---
title: Specificity
permalink: /css/specificity/
sidenav: css
---
# Specificity
......
---
title: Units
permalink: /css/units/
sidenav: css
---
# Units
......
---
title: Variables
permalink: /css/variables/
sidenav: css
---
# Variables
......
# Datastore selection guidance
---
title: Datastore Selection Guidance
---
# Datastore Selection Guidance
We're fortunate to have dozens of battle-tested datastores available to us,
filling many different niches and general use cases. Each has its own
......
---
title: Development Environments
---
# Development Environments
## Why this guide?
This guide discusses some principles we should strive to achieve when architecting development environments along with some examples techniques for achieving them. By following this guide, you'll learn how to create environments that are easy to setup, well-documented, and are reproducible (great for finding and fixing bugs). This will keep your colleagues happy, save you time from supporting developer ramp-up, make your repo much more likely to receive open source contributions, and is also generally a good practice as a matter of course.
......
## Example workflows
---
title: Example Workflows
---
## Example Workflows
Here we've collected descriptions of team processes (particularly around
submitting code) that various projects have used in the past. Please consider
......
---
title: 18F Front-End Guide
permalink: /
title: Front-End Disciplines
---
Welcome to the 18F Front-End Guide! This is where we keep all of our
guidelines for front-end design and development.
# Front-End Disciplines
## Related topics
* [CSS](/css)
* [JavaScript](/javascript)
* [Web Components](/web-components)
* [Security](/security)
## What is front end?
......
---
title: Cloud.gov post mortems
---
# Cloud.gov post mortems
Cloud.gov post mortems (including incident response) are hosted at
https://github.com/18F/cg-postmortems
# Incident reports
---
title: Incident Reports
---
# Incident Reports
Though we fully expect to write dependable applications, every project will
experience service disruptions and other significant failings. In all cases,
we want to learn from our mistakes both within our projects and more broadly.
......@@ -44,7 +47,7 @@ together and easy to reference by both the team and interested stakeholders.
Don't make folks search for the information.
## Examples
* [C2](./C2)
* [C2](./C2/c2-outage-report-2016-08-10.pdf)
* [Cloud.gov](./cloud_gov)
## Additional resources
......
---
title: 18F Engineering Practices Guide
---
A set of guidelines and best practices for an awesome engineering team
* [Front-End Disciplines](/frontend)
* [Third-Party Integrations](/integrations)
* [Workflow Best Practices](/workflow)
* [Example Workflows](/example_workflows)
* [Project Setup](/project_setup)
* [Architecture Reviews](/architecture_reviews)
* [Accessibility Scanning using AccessLint](/accessibility_scanning)
* [Feedback Guide](/people)
* [Continuous Deployment](/continuous_deployment)
* [Datastore Selection Guidance](/datastore_selection)
* [Security](/security)
* [Code Review](/code_review)
* [Development Environments](/development_environments)
* [Incident Reports](/incident_reports)
* [Polls](/polls)
* [Project Setup](/project_setup)
* [Tech Leads](/tech_leads)
### Language Guides
* [Language Selection Guidance](/language_selection)
* [JavaScript](/javascript)
* [Node.js](/nodejs)
* [Python](/python)
* [Ruby](/ruby)
* [CSS](/css)
---
title: Third-Party Integrations
---
# Third-Party Integrations
Our software is built on the shoulders of giants. We use several third parties
......
---
title: Dependencies
permalink: /javascript/dependencies/
sidenav: js
---
# Dependencies
......
---
title: Frameworks
permalink: /javascript/frameworks/
sidenav: js
---
# Frameworks
......
---
title: JavaScript
permalink: /javascript/
sidenav: js
---
......@@ -8,3 +7,6 @@ sidenav: js
The purpose of the JavaScript coding styleguide is to create and utilize
consistent JS across 18F. The styleguide should be treated as a guide
— rules can be modified according to project needs.
## Related topics
* [Node.js](/nodejs)
---
title: Libraries
permalink: /javascript/libraries/
sidenav: js
---
# Libraries
......
---
title: Style / Linting
permalink: /javascript/style/
sidenav: js
---
......
# Language selection guidance
---
title: Language Selection Guidance
---
# Language Selection Guidance
Many factors should influence how 18F engineers make technology selections
for their projects. Here, we discuss recommendations on how to select the
......
# Node/Javascript Development Guide
---
title: Node.js Development Guide
---
# Node.js Development Guide
## Related topics
* [JavaScript](/javascript)
## Introduction
This is a **WORK IN PROGRESS**. Help us make it better by [submitting an
issue](https://github.com/18F/development-guide) or joining us in the
......
---
title: 18F Engineering 2016 End of Year Assessment Guide
---
# 18F Engineering 2016 End of Year Assessment Guide
18F, as a part of GSA, has a mature [performance management and recognition system](https://insite.gsa.gov/portal/content/500278).
......
---
title: 18F Engineering 2017 End of Year Assessment Guide
---
# 18F Engineering 2017 End of Year Assessment Guide
18F, as a part of GSA, has a mature [performance management and recognition system](https://insite.gsa.gov/portal/content/500278).
......
---
title: Feedback Guide
---
# Feedback Guide
Here are some attributes of giving feedback in a highly constructive way that we have learned and used over the years.
......@@ -19,3 +22,11 @@ Don't dwell on the past, but focus on the future. The future can be altered, the
### Top Performers
Giving constructive feedback to a top performer is not nitpicking, it is actually some of the highest leverage work we can do. Most folks (not everyone of course) are eager to hear ways they can keep growing. We don't help folks by having no ideas for them.
### End of Year Assessment Guides
18F, as a part of GSA, has a mature [performance management and recognition system](https://insite.gsa.gov/portal/content/500278).
This includes an end-of-year performance assessment.
* [2016 Assessment Guide](/2016-Assessment-Guide)
* [2017 Assessment Guide](/2017-Assessment-Guide)
---
title: Polls
---
Here we collect (publicly visible) survey and poll results. In particular, we
create quick write-ups to summarize and contextualize the results.
......
---
title: NodeJS for Backend, Dec ‘16
---
# NodeJS for Backend, Dec ‘16
In preparation for a discussion about whether we should try to encourage or
discourage back end NodeJS apps, we created a brief survey about NodeJS back
end usage. We received 17 responses of roughly 80 solicited.
......
---
title: Silos and Soundness, Oct ‘16
---
# Silos and Soundness, Oct ‘16
Many of the issues we care about the most are very difficult to quantify. In
this survey, we asked three questions meant to gauge how engineers felt about
knowledge silos and the technical soundness of their projects. We invited all
......
---
title: Third-Party Tool Experience, Feb ‘18
---
# Third-Party Tool Experience, Feb ‘18
As we've begun to [define](/integrations/) a standard set of third-party
services we use in our apps, we wanted to measure existing familiarity. This
will help us determine where we should focus documentation and training
......
---
title: Docker for development
---
# Docker for development
Below we lay out recommendations for using Docker to wrap development
......
---
title: Project Setup
---
## Project Setup
While the specific setup for each 18F project varies widely, there are certain
......
---
title: Python Development Guide
---
# Python Development Guide
This is a **WORK IN PROGRESS**. Help us make it better by [submitting an
......
---
title: Ruby Guide
---
This is a **WORK IN PROGRESS**. Help us make it better by
[submitting an issue](https://github.com/18F/development-guide) or joining us
in the [#ruby](https://18f.slack.com/messages/ruby/) channel!
......
---
title: Content Security Policy
permalink: /security/content-security-policy/
sidenav: security
---
......
---
title: Security
permalink: /security/
sidenav: security
---
......
---
title: Output Enco
permalink: /security/output-encoding
title: Output Encoding
sidenav: security
---
# Output encoding
# Output Encoding
## What is cross site scripting (XSS)?
......
---
title: Tech Leads
---
# Tech Leads
## Current roster
......
---
title: Web Components
permalink: /web-components/
---
# Web components
# Web Components
## Initial Impressions
First, check out [this article](http://developer.telerik.com/featured/web-components-arent-ready-production-yet/) and [its follow-up](http://developer.telerik.com/featured/web-components-ready-production/) for some background on whether Web Components (or, more specifically, [custom elements]) are ready for production. TL;DR:
......
---
title: Workflow Best Practices
---
# Workflow Best Practices
Project teams may vary, but across 18F engineering we aim for consistency
......
---
name: Frontend
full_name: Frontend Guild
mission: |
Provide cross-team support to both frontend developers and 18F team members seeking tips and best practices in the frontend space.
links:
- url: 'https://drive.google.com/drive/#folders/0B84F26FpUP0lR1B2VVNGSi1MMVk/0B0C6PKlzps2JV3pqX3NJdm5WejA/0B5HeQa_YQ6-VTTlkVEFNZ2VWZEU'
text: Google Drive folder
github_repos:
- 18F/frontend-style-guide
leads:
- marco
- mhz
members:
- marco
- mhz
- julia
owner_type: guild
_site/
.sass-cache/
.DS_store
.*.swp
## Building the guide locally
The Front-End Guide is built on the [USWDS Jekyll theme gem](https://github.com/18F/uswds-jekyll).
To run it locally, clone this repo and then:
1. Install [http://bundler.io/](Bundler) if you don't already have it: `gem install bundler`
1. Run `bundle install`.
1. Run `bundle exec jekyll serve`.
## Submitting a pull request
We welcome pull requests! Here's how to submit a PR:
1. The guide publishes the `master` branch, so make sure you have the latest version of it.
1. Create a new branch named in a way that describes your changes, optionally prefixed with your initials. Example: Heather Billings wants to create a PR that adds guidance around atomic CSS. She calls her branch `hjb-add-atomic-css`.
1. Push your branch and open a work-in-progress (WIP) PR as soon as you have commits, rather than waiting until you feel you are finished. **A WIP PR includes `[WIP]` in the title and contains a list of unfinished tasks.** WIP PRs allow for early feedback and help prevent wasted time. It also allows other guild members to pick up and work on pull requests that have been abandoned for whatever reason.
1. When your PR is ready for review, remove `[WIP]` from the title. This lets us know it's game time!
1. A PR must pass the automatic Federalist build check in order to be merged into master.
1. A PR must have one `approved` review in order to be merged into master. Any guild member with write access should be able to approve and merge PRs. (You cannot approve your own PR, sorry!)
## Submitting issues
Don't have time to file a pull request, but want to flag something? [Open an issue](https://github.com/18F/frontend/issues) stating what you think we should add or change and why, and we'll discuss it as a group.
## Public domain
This project is in the public domain within the United States, and
copyright and related rights in the work worldwide are waived through
the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).
All contributions to this project will be released under the CC0
dedication. By submitting a pull request, you are agreeing to comply
with this waiver of copyright interest.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.