Merge pull request #1 from baccigalupi/kane-recipes

Kane recipes
18F · Sep 11, 2015 · d1237cc · d1237cc
2 parents e3ccc44 + 89d1b74
commit d1237cc
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 4 deletions.
diff --git a/recipes/api-first.yml b/recipes/api-first.yml
@@ -7,7 +7,7 @@ ingredients:
 - A read API
 - A data portal website
 directions:
-- "If starting on a brand new application or service, build out a robust REST API in accordance with the agency's applicable API standards. Otherwise, the first thing to do will be to ensure that you can build out a new API on an existing service or build out the existing API to ensure that it can power the desired presentation interface. This will involve some judgment about which approach to take. But the goal is to ensure that a clean, robust API is available."  
+- "If starting on a brand new application or service, build out a robust REST API in accordance with the agency's applicable API standards. Otherwise, the first thing to do will be to ensure that you can build out a new API on an existing service or build out the existing API to ensure that it can power the desired presentation interface. This will involve some judgment about which approach to take. But the goal is to ensure that a clean, robust API is available."
 - "Once you have an API, ensure that your presentation interface is built using the API. Expect that, as the presentation interface matures, there will be a need to optimize and refine the design of the API itself. This is a good, and natural result of an API-First approach."
 - "Make sure that the API is well documented, so that it is easier to make future changes to the presentation interface (or adoption of alternative presentations)."
 snippets: "Finally, Treasury requires that the source of data used in the site be the outbound API."

diff --git a/recipes/open-source.yml b/recipes/open-source.yml
@@ -2,7 +2,7 @@ title: "Open Source Software"
 description: |
   "Both the [US Digital Services playbook](https://playbook.cio.gov) and the [18F open-source policy](https://github.com/18F/open-source-policy/blob/master/policy.md) strongly suggest the use and creation of open-source software in the creation of digital services. Specifically, the 18F policy provides that the 'default position' should be to 'Use Free and Open Source Software (FOSS), which is software that does not charge users a purchase or licensing fee for modifying or redistributing the source code, in our projects and contribute back to the open source community.' Based on this default position, vendors who are developing software for the government should also use and create open-source software. In a recent solicitation from the Department of Defense, the government included a requirement that all deliverables by made available to the public as open-source software, and more importantly, affords the government the authority to select the applicable license.
 
-  There are permutations of the language, but 18F's favorite recipe involves requiring not only open-source software, but further requires that all software delivered be dedicated to the public domain under a Creative Commons Zero (CC0) license." 
+  There are permutations of the language, but 18F's favorite recipe involves requiring not only open-source software, but further requires that all software delivered be dedicated to the public domain under a Creative Commons Zero (CC0) license."
 ingredients:
 - A requirement for new software deliverables
 - One or more publicly available source-code repositories
@@ -13,6 +13,6 @@ directions:
 - "Make sure that your vendors understand, whether during an RFI or industry day, that open-source software is important for your project."
 - "Include in your solicitation a requirement for open-source software. If you have a preferred license, specify it in the solicitation. If not, give yourself the flexibility to choose a license at a later point."
 - "Make sure that your contractor holds to the open-source requirement, and require the contractor to provide all licenses for software dependencies as part of the deliverables." 
-snippets: "The Contractor shall develop all source code that should become property of the Government, for software deliverables which shall be made available by the contractor to the public as open source software, under the terms and conditions of a license determined or approved by the Government." 
+snippets: "The Contractor shall develop all source code that should become property of the Government, for software deliverables which shall be made available by the contractor to the public as open source software, under the terms and conditions of a license determined or approved by the Government."
 ags:
-- Open Source 
+- Open Source
diff --git a/recipes/source-control.yml b/recipes/source-control.yml
@@ -0,0 +1,15 @@
+title: "Source Control"
+description: |
+  "The [US Digital Services playbook](https://playbook.cio.gov) recommends using a 'source code version control system' while developing digital services. Source control, also known as version control, is a tool that tracks history of changes made to code base. History is recorded via a series of commits. Source control systems usually allow rolling back to previous states, which can be essential when bad code is commited to the code base accidentally. More information on the benefits and features of source control systems are described on [Wikipedia](https://en.wikipedia.org/wiki/Version_control).
+  In addition to providing rollback capabilities, source control is important for code bases with multiple contributors. Each commit encapsulates the intent of the change to the code base, and when two contributors edit the same file or even the same line, the version control system will recognize the conflict, preventing lost work.
+  Source control tools are also heavily used in modern software engineering as an integration point for other important tools. A commit to the master repository can trigger automated test builds, static analysis or even a deploy."
+ingredients:
+- A code base
+- "A source control tool. Recommended source control tools are [git](https://git-scm.com) and [mercurial](https://mercurial.selenic.com). Both are [distributed](https://en.wikipedia.org/wiki/Distributed_version_control) source control systems."
+- A central repository to act as the source of truth for the code base
+directions:
+- "Preheat - Prepare your repository for source control: Some binary files are not appropriate for source control. In the case of large binary files, the file changes cannot be comprehended easily by mere mortals, so recording the differences in the files looses its meaning. Also, binary files are often very large, requiring massive transfer bandwidth. Binaries are appropriate when an integral part of the history. For example, many images are relevant and changing resources in a web application. Omiting them from the repository would cause more pain than gain. Careful thought should go into what should be in and out of the repository. Source control tools allow ignoring files."
+- Learn your source control tool. Both recommended tools are open source with great tutorials and community support. You can get rapid benefits without having to fully know your tool.
+- "Create a central repository to act and the source of truth. 18F uses git as a tool and hosts repositories via [Github](https://github.com). Mercurial repositories can be likewise hosted on the service [Bitbucket](https://bitbucket.org/). It is possible to roll your own repository host on a server, but it is likely that the laws governing your digital content allow source control hosting via a cloud service."
+tags:
+- Source Control