Skip to content

Commit

Permalink
documentation updates
Browse files Browse the repository at this point in the history
  • Loading branch information
coreycaitlin committed Oct 13, 2016
1 parent d7788e0 commit 70a8327
Show file tree
Hide file tree
Showing 3 changed files with 112 additions and 77 deletions.
128 changes: 79 additions & 49 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,91 @@
This is a repo to design a beta version of 18f.gsa.gov using the [U.S.
Web Design Standards](https://standards.usa.gov/) and to completely refresh most of the content.

## Where Contributions Go

Thanks for planning to contribute. Please read the guidelines below to know what to expect before submitting a contribution. Submit contributions to https://github.com/18F/18f.gsa.gov as pull requests to the `master` branch. 18F team members should submit pull requests from a branch. Outside contributors will need to fork this repo.

## Front end architecture
### CSS
- Styling will be built from the [U.S.
Web Design Standards(**WDS**)](https://standards.usa.gov/).
- CSS methodology will be inherited from the WDS, which inherits mostly from the [18f front end guide](https://pages.18f.gov/frontend/css-coding-styleguide/architecture/).
- Use [18F modifed BEM naming convention](https://pages.18f.gov/frontend/css-coding-styleguide/naming/)
- Componentized CSS: start with tag rules and only becomes more specific as necessary, using component classes.
- The 18F-site team will update the WDS library when it publishes a change required by the site. Otherwise it will only update bi-monthly (see #1877).
- The codebase will be visual regression tested when a suitable tool is found for 18F.
- The Sass code should be linted with `scss-lint` (see #1878)
- The [18F CSS linting configuration](https://raw.githubusercontent.com/18F/frontend/18f-pages-staging/.scss-lint.yml) will be used.
- If linting fails, it will also fail the tests, but not the build.
- The website should default to [semantic HTML5](http://www.w3schools.com/html/html5_semantic_elements.asp).


### Images
- All icons should use `<svg>` and `xlink` (looking for link) formats.
- All blog images should be under 800kb in total, un-minified size.
This is a repo to design a beta version of 18f.gsa.gov using the [U.S. Web Design Standards](https://standards.usa.gov/) and to completely refresh most of the content.

In this document:

* [Public contributions](#public-contributions)
* [18F contributions](#18f-contributions)
- [Branches](#branches)
- [Front end architecture](#front-end-architecture)
- [Standards and benchmarks](#standards-and-benchmarks)
* [Public domain](#public-domain)

## Public contributions

We're so glad you're thinking about contributing to an 18F open source project! If you're unsure about anything, just [send us an email](mailto:[email protected]) with your question — or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions.

We want to ensure a welcoming environment for all of our projects. Our staff follow the [18F Code of Conduct](https://github.com/18F/code-of-conduct/blob/master/code-of-conduct.md) and all contributors should do the same.

We encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](LICENSE.md), and its [README](README.md).

* If you see an error or have feedback, the best way to let us know is to file an issue.
* To contribute a specific change to the site, outside contributors will need to fork this repo.

## 18F contributions

There is a team actively working on the site. You can find us in Slack in the #18f-site or #beta-18F-site channels (limited access).

### Branches

Any 18F team member should be able to make a branch of the site and submit a pull request. Doing so will also generate a preview URL we can use to inspect your changes.

Because new blog posts are published several times a week, we use several branches to manage parallel work in a predictable way:

* Submit **blog posts and minor content edits** as pull requests to the `master` branch.
* Submit **new design work, content changes, and features** as pull requests to the `dev` branch. This will allow us to test and review batches of changes before deploying them.

**The `master`, `staging`, and `production` branches are protected.** Only administrators of the repo can push directly to those branches. 18F teammates who don’t think they have the correct permissions should ask in the #18f-site channel.

### Front end architecture

This site is based on the [U.S.
Web Design Standards](https://standards.usa.gov/) (WDS). It is developed using [Jekyll](https://jekyllrb.com/), a static site generator based on the Ruby programming language.

We default to using [semantic HTML5](http://www.w3schools.com/html/html5_semantic_elements.asp).

We use [HoundCI](https://houndci.com/) to automate Sass, JavaScript, and Ruby linting.

We use [CircleCI](https://circleci.com/) to run HTML Code Sniffer.

#### CSS

CSS methodology is inherited from the WDS, which inherits mostly from the [18f front end guide](https://pages.18f.gov/frontend/css-coding-styleguide/architecture/).

- Use [18F modifed BEM naming convention](https://pages.18f.gov/frontend/css-coding-styleguide/naming/)
- Componentized CSS: start with tag rules and only becomes more specific as necessary, using component classes

The 18F-site team will update the WDS library when it publishes a change required by the site; otherwise it will update bi-monthly (see [issue #1877](https://github.com/18F/18f.gsa.gov/issues/1877))

#### Images

- All icons should use `<svg>` and `xlink` (looking for link) formats
- All blog images should be under 800kb in total, un-minified size
- Images should be under 600Kb after being minified
- All raster images should be minified with a tool such as [grunt-imagemin](https://github.com/gruntjs/grunt-contrib-imagemin).
- All raster images should be minified with a tool such as [grunt-imagemin](https://github.com/gruntjs/grunt-contrib-imagemin)

#### JavaScript

### JavaScript
- The website is developed using [Jekyll](https://jekyllrb.com/) , a static site generator based on the Ruby programming language.
- The website is also required to work without JavaScript and no heavy Javascript framework is used.
- jQuery will be required for the WDS
- The website github project uses the [AirBnB linter configuration for JavaScript](https://github.com/airbnb/javascript/tree/master/packages/eslint-config-airbnb), if linting fails, it will also fail the tests, but not the build. (See: #1879)
- Ruby gems will be used for front end dependency management.
- JavaScript will not be bundled.
- There will be a manual testing script that will be required to walk through for each Pull Request.
This site does not use any heavy JavaScript frameworks, and should always work without JavaScript.

- jQuery is included in the WDS
- Ruby gems is used for front end dependency management

### Devices
- The website supports all versions of Internet Explorer still supported by Microsoft, as well as the newest Chrome and FireFox.
- The website should be designed with a mobile-first approach.
- Every applicable change should be run through HTML code sniffer.
## Standards and benchmarks

### Device and browser support

- The website supports all versions of Internet Explorer still supported by Microsoft, as well as recent versions of Chrome, Safari, and Firefox
- The website should be designed with a mobile-first approach

### Performance
- Performance will be measured against the following custom events:
- Time to blog post image
- Time to main image and callout text.
- Time until first blog post title shows up on page with all blog posts.
- Each of these should load in under a second

Each of the following events should load in under a second:

- Time to blog post image
- Time to main image and callout text
- Time until first blog post title shows up on page with all blog posts

## 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/).
For detailed license information, see [LICENSE](LICENSE.md).

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.
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.
47 changes: 26 additions & 21 deletions LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,37 @@
As a work of the United States Government, this project is in the
public domain within the United States.
This project includes a mix of the following:

Additionally, we waive copyright and related rights in the work
worldwide through the CC0 1.0 Universal public domain dedication.
* Open source work that are not in the public domain
* Open source work by the U.S. government that is in the public domain

## CC0 1.0 Universal Summary
## Parts of this project that are not in the public domain

This site is based on the Draft U.S. Web Design Standards (WDS), which also includes works under the SIL Open Font License, MIT license, and public domain. Files from the WDS are in `_sass/_libs/wds/`, and the full license details for those assets are described in the [WDS license file](https://github.com/18F/web-design-standards/blob/staging/LICENSE.md).

This site also includes a number of images that have various copyright statuses, including Creative Commons licenses and public domain. These images are in the `assets` directory, and license details are available on the posts and pages that display the images.

## The rest of this project is in the worldwide public domain

As a work of the United States government, this project is in the public domain within the United States.

Additionally, we waive copyright and related rights in the work worldwide through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/).

### CC0 1.0 Universal Summary

This is a human-readable summary of the
[Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).

### No Copyright
#### No copyright

The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.

You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.

The person who associated a work with this deed has dedicated the work to
the public domain by waiving all of his or her rights to the work worldwide
under copyright law, including all related and neighboring rights, to the
extent allowed by law.
#### Other information

You can copy, modify, distribute and perform the work, even for commercial
purposes, all without asking permission.
In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights.

### Other Information
Unless expressly stated otherwise, the person who associated a work with this deed makes no warranties about the work, and disclaims liability for all uses of the work, to the fullest extent permitted by applicable law. When using or citing the work, you should not imply endorsement by the author or the affirmer.

In no way are the patent or trademark rights of any person affected by CC0,
nor are the rights that other persons may have in the work or in how the
work is used, such as publicity or privacy rights.
### Contributions to this project

Unless expressly stated otherwise, the person who associated a work with
this deed makes no warranties about the work, and disclaims liability for
all uses of the work, to the fullest extent permitted by applicable law.
When using or citing the work, you should not imply endorsement by the
author or the affirmer.
As stated in [CONTRIBUTING](CONTRIBUTING.md), 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.
14 changes: 7 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
# 18F's flagship website
# 18F’s flagship website

A fresh start for 18f.gsa.gov. Online at beta.18f.gov. We use the [Draft U.S. Web Design standards](https://standards.usa.gov/) as a frontend framework. The site is built and served through [the Federalist platform](https://federalist.18f.gov). A detailed history of the work that went into developing this redesign can be found at [18F/beta.18f.gov](https://github.com/18F/beta.18f.gov) and an archived copy of the original website, can be found [on a Federalist preview](https://federalist.18f.gov/preview/18F/18f.gsa.gov/staging).
This repo houses the 18F website. We use the [Draft U.S. Web Design standards](https://standards.usa.gov/) as a front end framework. The site is built and served through [the Federalist platform](https://federalist.18f.gov).

### History

A detailed history of the work that went into developing this redesign can be found at [18F/beta.18f.gov](https://github.com/18F/beta.18f.gov). An archived copy of the original website can be found [on a Federalist preview](https://federalist.18f.gov/preview/18F/18f.gsa.gov/staging).

## Installation

Run each of the following steps to get the site up and running.

<!-- THESE INSTRUCTIONS ONLY WORK FOR 18F FOLK -->
1. `git clone [email protected]:18F/18f.gsa.gov`
2. `cd 18f.gsa.gov`
3. `bundle install`
Expand All @@ -26,14 +31,9 @@ The site is a static website with HTML, CSS, and Javascript. Deployments are don
1. Federalist responds to a webhook on GitHub and runs Jekyll to generate static web files and puts them in an S3 bucket
1. We map 18f.gsa.gov URL to the S3 bucket

### Protected branches

Any 18F team member should be able to make a branch of the site and submit a pull request. Doing so will also generate a preview URL we can use to inspect your changes. **The `master` `staging` and `production` branches are protected** this means that only administrators of the repo can push directly to those branches. 18F teammates who don't think they have the correct permissions should hit us up in the #18f-site channel.

### Constraints

* We use Cloudfront to map 18f.gsa.gov to an S3 endpoint
* IE 9 and above
* Federalist, and Cloudfront do not support the following HTTPS implementations:
* [HSTS Headers](https://github.com/18F/18f.gsa.gov/issues/1871)
* [HTTP/2](https://github.com/18F/18f.gsa.gov/issues/1872)
Expand Down

0 comments on commit 70a8327

Please sign in to comment.