NOTE: This CONTRIBUTING.md is for software contributions. You do not need to follow the Developer's Certificate of Origin (DCO) process for commenting on the Code.mil repository documentation, such as CONTRIBUTING.md, INTENT.md, etc. or for submitting issues.
Thanks for thinking about using or contributing to this software ("Project") and its documentation!
The project maintainer for this Project will only accept contributions using the Developer's Certificate of Origin 1.1 located at developercertificate.org ("DCO"). The DCO is a legally binding statement asserting that you are the creator of your contribution, or that you otherwise have the authority to distribute the contribution, and that you are intentionally making the contribution available under the license associated with the Project ("License").
Before submitting contributing code to this repository for the first time, you'll need to sign a Developer Certificate of Origin (DCO) (see below). To agree to the DCO, add your name and email address to the CONTRIBUTORS.md file. At a high level, adding your information to this file tells us that you have the right to submit the work you're contributing and indicates that you consent to our treating the contribution in a way consistent with the license associated with this software (as described in LICENSE.md) and its documentation ("Project").
Pseudonymous or anonymous contributions are permissible, but you must be reachable at the email address provided in the Signed-off-by line.
If your contribution is significant, you are also welcome to add your name and copyright date to the source file header.
U.S. Federal law prevents the government from accepting gratuitous services unless certain conditions are met. By submitting a pull request, you acknowledge that your services are offered without expectation of payment and that you expressly waive any future pay claims against the U.S. Federal government related to your contribution.
If you are a U.S. Federal government employee and use a *.mil or *.gov email address, we interpret your Signed-off-by to mean that the contribution was created in whole or in part by you and that your contribution is not subject to copyright protections.
The full text of the DCO is included below and is available online at developercertificate.org:
Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.Code.mil is a static website generated using Jekyll, a static website generator written in the Ruby programming language. Development dependences are managed using the Bundler gem.
This project uses Ruby version 2.6.2 which may be installed using a Ruby version manager like rbenv, chruby, or rvm.
rbenv install 2.6.2Once you've installed Ruby 2.6.2 and the Bundler gem (gem install bundler), install the project's gems by running::
bundle installNow you're ready to clone the repository locally and start making changes. The website's source code is in the src folder which contains content pages authored in the Markdown text format. Jekyll configuration is defined in the src/_config.yml file. Additional configuration files are located in the src/_data folder.
Once you've installed the project's dependencies as outlined above, you're ready to run Jekyll and browse the website locally:
./scripts/serveThis command will build the website to the public folder and start up a local server, making the website available at http://localhost:4000 (or http://127.0.0.1:4000). Fire up your favorite Web browser to view the website locally!
Code formatting conventions are defined in the .editorconfig file which uses the EditorConfig syntax. There are plugins for a variety of editors that utilize the settings in the .editorconfig file. It is recommended that you install the EditorConfig plugin for your editor of choice.
Your bug fix or feature addition won't be rejected if it runs afoul of any (or all) of these guidelines, but following the guidelines will definitely make everyone's lives a little easier.
You should feel free to submit an issue on our GitHub repository for anything you find that needs attention on the website. That includes content, functionality, design, or anything else!
When submitting a bug report on the website, please be sure to include accurate and thorough information about the problem you're observing. Be sure to include:
- Steps to reproduce the problem,
- The URL of the page where you observed the problem,
- What you expected to happen,
- What actually happend (or didn't happen), and
- Technical details including your Operating System name and version and Web browser name and version number.
When making your changes, it is highly encouraged that you use a branch in Git, then submit a pull request (PR) on GitHub. Your pull request will go through some automated checks using Travis CI, a continuous integration and deployment tool.
After review by the Code.mil team, your PR will either be commented on with a request for more information or changes, or it will be merged into the master branch and deployed to a URL for testing purposes.
Assuming everything checks out, the Code.mil team will merge the master branch into the production branch which will be automatically deployed to the production hosting environment, making your changes available on code.mil.
Note that if you're updating content on policy-specific pages (e.g. Getting Started, How to Open Source, Frequently Asked Questions), be sure to update the updated_at value in the file's YAML Front Matter (in the format YYYY-MM-DD):
---
title: Getting Started
updated_at: 2018-04-03
---Before submitting your pull request, you should run the build process locally first to ensure things are working as expected.
./scripts/buildYou should also run the testing script against your local build. This script will check the built website using the html-proofer Ruby gem. You may run the test script using the following command:
./scripts/testIf you have a project that you have open sourced, then you need to add (or update) your project in the code inventory file that the DoD uses to comply with OMB Policy (M-16-21). You can read more about the format of the code inventory format on the Code.gov website.
To add your project you will need to submit a Pull Request to this project on GitHub. You can follow the instructions here for doing so, but if you are not familiar with GitHub, you can also just tell us about your project and we can get the process started.
Each open sourced project is represented by a JSON object block in the final code.json file. In order to make it easy for us to manage the JSON data, each project is represented as a separate file in our code repository. You can see an example of a project for the US Army Research Lab in the repo.
Start by forking our repository, and then creating a file within the "_releases" directory. This file should have a name that matches your project and should be a JSON file with a single object ({ ... }) at the root. For example, your file might be called "foobar.json" with this content:
{
"name": "FooBar",
"organization": "DoD FooBar",
"description": "A project to track all the foobars in the DoD.",
"tags": [ "foo", "bar", ... ],
...
}
Note the file structure in the repo! It starts at "_releases" and then goes to the domain it is hosted on such as "github.com" or "gitlab.com". Under that each organization or user account is represented, followed by the project's json file. For example, our "FooBar" project above may be located here:
src/_releases/github.com/MyOrg/foobar.json
Once you have your JSON file created you should build and run the site locally to ensure everything works, then submit your pull request. To test the site, run the commands listed above for "Getting Started" and for "Making Changes". You should now be able to see the compiled JSON file at http://0.0.0.0:4000/code.json. Look through that file to find your project. If it shows up, you should be good!
Now you need to submit your Pull Request to the base Code.mil website repository. Be sure to fill out the description of why this change is being done and that you tested things! We'll check the work and then merge the code into our base and it will be live in minutes.