Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
168 lines (104 loc) · 7.03 KB

CONTRIBUTING.md

File metadata and controls

168 lines (104 loc) · 7.03 KB
Raw

How to Contribute

We're so thankful you're considering contributing to an open source project of the U.S. government! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We appreciate all friendly contributions.

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

Getting Started

Index Generator Website is a static site built with plain HTML, CSS, and JavaScript. There is no build step and no package dependencies.

To run the project locally,

  1. Start up a HTTP server using python: python3 -m http.server 8000
  2. Open http://localhost:8000 in your browser. Right click and choose inspect to open developer tools for troubleshooting
  3. Fill out the form and click Generate Index, which triggers a local download of the combined index.json

Team Specific Guidelines

  • Please try to keep pull requests to a reasonable size; try to split large contributions to multiple PRs
  • Please create pull requests into main
  • Document and explain the contribution clearly according to provided standards when possible
  • Feel free to reach out to us if there is any confusion. A list of the project maintainers is found here: COMMUNITY.md

Building dependencies

There are no dependencies to install. Python (or any static file server) is only needed to serve the site locally.

Building the Project

  1. Start up a HTTP server using python: python3 -m http.server 8000

Workflow and Branching

We follow the GitHub Flow Workflow

  1. Fork the project
  2. Check out the main branch
  3. Create a feature branch
  4. Write code and tests for your change
  5. From your branch, make a pull request against DSACMS/index-generator-website/main
  6. Work with repo maintainers to get your change reviewed
  7. Wait for your change to be pulled into DSACMS/index-generator-website/main
  8. Delete your feature branch

Testing Conventions

There are no automated tests at the moment. Before opening a pull request, please manually verify the following in a browser:

  • Generating an index for a known organization (e.g. DSACMS) downloads an index.json and the success/failed counts match the repositories listed
  • Generating a second time clears the results of the previous run
  • Invalid organization names and missing required fields show a clear error message
  • The page is usable with a keyboard only and at mobile widths (~375px)
  • The browser console shows no errors

Coding Style and Linters

Please match the style of the surrounding code. Never insert untrusted data (such as content from a fetched code.json) into the page with innerHTML; use textContent instead.

Writing Issues

When creating an issue please try to adhere to the following format:

module-name: One line summary of the issue (less than 72 characters)

### Expected behavior

As concisely as possible, describe the expected behavior.

### Actual behavior

As concisely as possible, describe the observed behavior.

### Steps to reproduce the behavior

List all relevant steps to reproduce the observed behavior.

Writing Pull Requests

Comments should be formatted to a width no greater than 80 columns.

Files should be exempt of trailing spaces.

We adhere to a specific format for commit messages. Please write your commit messages along these guidelines. Please keep the line width no greater than 80 columns (You can use fmt -n -p -w 80 to accomplish this).

module-name: One line description of your change (less than 72 characters)

Problem

Explain the context and why you're making that change.  What is the problem
you're trying to solve? In some cases there is not a problem and this can be
thought of being the motivation for your change.

Solution

Describe the modifications you've done.

Result

What will change as a result of your pull request? Note that sometimes this
section is unnecessary because it is self-explanatory based on the solution.

Some important notes regarding the summary line:

  • Describe what was done; not the result
  • Use the active voice
  • Use the present tense
  • Capitalize properly
  • Do not end in a period — this is a title/subject
  • Prefix the subject with its scope

Reviewing Pull Requests

When you submit a pull request on GitHub, it will be reviewed by the project community, and once the changes are approved, your commits will be brought into the main branch, which deploys the production website through GitHub Pages.

Reviewers are listed in COMMUNITY.md and code owners are listed in CODEOWNERS.md.

Shipping Releases

Changes are released continuously: every merge to main is deployed to the live site at https://dsacms.github.io/index-generator-website/ by GitHub Pages.

Documentation

We also welcome improvements to the project documentation or to the existing docs. Please file an issue.

Policies

Open Source Policy

We adhere to the CMS Open Source Policy. If you have any questions, just shoot us an email.

Security and Responsible Disclosure Policy

Submit a vulnerability: Vulnerability reports can be submitted through Bugcrowd. Reports may be submitted anonymously. If you share contact information, we will acknowledge receipt of your report within 3 business days.

For more information about our Security, Vulnerability, and Responsible Disclosure Policies, see SECURITY.md.

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.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request or issue, you are agreeing to comply with this waiver of copyright interest.