Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
168 lines (121 loc) · 6.55 KB

CONTRIBUTING.md

File metadata and controls

168 lines (121 loc) · 6.55 KB

Welcome

We’re glad you’re thinking about contributing to an 18F open source project! If you’re unsure about anything, ask us — or submit the issue or pull request anyway. The worst that can happen is that we’ll politely ask you to change something.

We love all friendly contributions, and we welcome your ideas about how to make USEITI’s online presence more user friendly, accessible, and elegant.

To ensure a welcoming environment for our projects, our staff follows the 18F Code of Conduct; contributors should do the same. Please also check out the 18F Open Source Policy.

Running and testing the site

This site is made with [Jekyll]. To run it locally, clone this repository then:

  1. Get [Jekyll] and the necessary dependencies: bundle install
  2. Install all node dependencies: npm install
  3. Package js files with webpack: webpack --watch
  4. Run the web server: npm run start (or jekyll serve if you have Jekyll installed globally)
  5. Visit the local site at http://localhost:4000

Data and database

The data catalog explains what most of the data is and where it came from. See the data directory for more detailed info and instructions on updating the data.

Data for the site is populated via data files in the _data directory. These are primarily yml files that are generated from commands in the Makefile.

To create the database locally, make sure that you have sqlite and run make db.

If you would like to query the local database instance:

  1. Open a new terminal shell and run sqlite3
  2. Run .open data.db
  3. You can now run sqlite queries from the local instance.
  4. Run .tables to see the available tables you can query.

To update site data, run make site-data.

Deployment

This site is deployed on Federalist whenever a commit it pushed to GitHub. Changes are deployed automatically to the production site when commits are pushed to the master branch.

If deploying the site to a production environment, make sure to minify the JS files:

  1. Set the $NODE_ENV to prod: export NODE_ENV=prod
  2. Package js files with webpack: webpack --watch
  3. Re-run the web server: bundle exec jekyll serve

Styleguide

npm install --dev
npm run init-styleguide
cd styleguide-template && npm install
cd ..
npm run watch-styleguide

Tests

JavaScript

The JavaScript tests currently cover all datasets. You can run them with [Node]:

npm install --dev
npm test

Jekyll filters

We have created a set of custom Jekyll filters that can be used for templating. The filters in plugins/eiti*.rb are tested with rubydoctest.

Testing filters

You can run the unit tests as follows:

npm test-ruby
Writing filters

As the following example demonstrates, test cases are written in comment blocks immediately preceding a testable function. The test description is on the first line, with an empty comment block below it. Use >> syntax to invoke a test case, and follow it with hash rocket syntax, =>, to define the expected outcome of the invocation.

Inline unit test for to_i:

# attempt to look up a term in a hash, and return the value if that
# key exists; otherwise, return the key
#
# >> EITI::Data.lookup('hi', {'hi' => 'hello'})
# => 'hello'
# >> EITI::Data.lookup('yo', {'hi' => 'hello'})
# => 'yo'
def lookup(term, hash)
  hash.key?(term) ? hash[term] : term
end

Continuous integration

We are using CircleCI to test our code as we push it to Github.

As specified in our circle.yml configuration file, we are running our JavaScript and Jekyll filter tests to ensure that functions are working as expected.

Code style

We use Hound CI to enforce SCSS and JavaScript formatting conventions on new commits. You can run both of the linters with:

npm run lint

This runs both of the linters below in series.

JavaScript linting

Hound uses jshint, which you can install as part of the npm package's devDependencies with:

npm install --dev

Or you can install it globally with npm i -g jshint. Then, to lint the JavaScript, run:

npm run lint-js
SCSS linting

Hound uses scss-lint, which you can install with gem install scss_lint if you haven't already run bundle install to get Jekyll and its dependencies. To lint the SCSS files, run:

bundle exec scss-lint -c .scss-lint.yml

or simply:

npm run lint-scss

Process and workflow

Issues

When you open an issue, fill out all relevant fields in the issue template and include links to any prior related pull requests or issues.

Pull requests

  • Create pull requests for all commits, even typo fixes. This helps us track work and increase visibility into current work going on.
  • When you open a pull request, complete the template to make sure reviewers have all the information they need.
  • Use cc @username to notify a specific team member to review a pull request.
  • While working, submit [WIP] pull requests liberally.
  • Anyone may informally review a pull request and make comments or suggestions.
  • Don’t merge your own pull request. Ask a colleague to review your code and merge. This helps ensure that at least two people have verified the quality of the code and/or content.

Public domain

By submitting a pull request, you agree to comply with the policies on our LICENSE page:

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.

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.