Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
203 lines (138 loc) · 7.29 KB

CONTRIBUTING.md

File metadata and controls

203 lines (138 loc) · 7.29 KB

Contributing to PlanDev UI

Thanks for taking the time to consider contributing! We very much appreciate your time and effort. This document outlines the ways you can contribute to PlanDev UI and the conventions we follow.

Prerequisites

License

Our project's licensing terms are documented in LICENSE. Please review it before contributing — it impacts how your contributions may be redistributed.

Code of Conduct

We follow the Contributor Covenant. By participating, you agree to its terms.

Developer Environment

For details on running, building, and testing PlanDev UI locally, see:

At a minimum you'll need:

  1. A GitHub account
  2. Git installed locally
  3. Node.js (see .nvmrc) and npm
  4. The ability to build and test the project on your local machine

Communication Channels

Before contributing, it's a good idea to socialize your idea early. Our channels are:

Our Development Process

flowchart TD
    repo_proj[(NASA-AMMOS/plandev-ui)]-->|Fork|repo_fork[(Your Fork)]
    repo_fork-->|Branch off develop|patch(Your Changes)
    patch-->|Submit|pr(Pull Request)
    pr==>|Approved + Squash & Merge|repo_proj
    pr-->|Changes Requested|repo_fork
Loading

We integrate changes through pull requests against the develop branch. Forking is preferred over direct branching for external contributors; core team members typically branch directly.

Find or File an Issue

Make sure people know what you're working on. Check the issue tracker for a related issue, or file a new one to start the conversation.

Choose the Right Branch

develop is the default branch and the integration target for all new work. Branch off develop.

Submitting a Pull Request

  1. Search GitHub for an open or closed PR that relates to your submission to avoid duplicating effort.

  2. Confirm an issue describes the problem or feature. Discussing the design up front helps ensure the work will be accepted.

  3. Clone the NASA-AMMOS/plandev-ui repo (or your fork).

  4. Create a branch off develop:

    git checkout develop
git pull origin develop
git checkout -b my-fix-branch develop

  5. Make your changes.

  6. Follow our Coding Rules.

  7. Commit your changes:

    git commit -a

    The optional -a flag will automatically add and rm edited files. Intra-PR commits get squashed at merge time, so their shape is up to you — what matters is the PR title and label.

  8. Push your branch:

    git push origin my-fix-branch

  9. Open a pull request against plandev-ui:develop.

Responding to Review

If reviewers request changes:

  • Make the updates and follow the Coding Rules.

  • Rebase and force-push to update the PR:

    git rebase develop -i
git push -f

If your branch falls behind develop:

  • Rebase locally as above, or
  • Use the GitHub UI's "Update branch" dropdown → "Update with rebase".

Merging

Once approved, prefer Squash and merge to keep develop history clean. Update the squash commit message body to include only what's relevant. Do not modify the PR title at squash time — that breaks our release-notes tracking.

After merge:

git push origin --delete my-fix-branch   # delete remote branch
git checkout develop                      # back to develop
git pull origin develop                   # pull the merged change
git branch -D my-fix-branch              # delete local branch

Coding Rules

Before opening a PR, run:

  1. npm run format:write
  2. npm run lint
  3. npm run lint:css
  4. npm run check
  5. Follow the testing procedures in docs/TESTING.md

Pull Request Title and Labels

PRs are squash-merged, so the PR title becomes the commit on develop. Use a descriptive sentence — recent examples:

  • "Allow sequence name to be chosen during filter application"
  • "Swap table cookie persistence for localStorage"
  • "Fix inconsistent file extension handling in workspaces"

For release-note categorization, apply one of the labels configured in .github/release.yml:

Label Category
breaking change Breaking Changes
feature New Features
fix Bug Fixes
performance Performance Improvements
refactor Refactoring
test Testing
ci Continuous Integration
documentation Documentation
build Build System and Dependencies
style Style

PRs without a matching label fall under "Other Changes".

Ways to Contribute

Code

Before writing code, check the issue tracker:

  1. Look for duplicate issues covering your idea — comment there with your thoughts.
  2. If none exist, file a new issue and start a conversation before opening a PR.

When ready to contribute code:

  1. Make sure development prerequisites are met.
  2. Follow our development process.
  3. Open a PR per Submitting a Pull Request.

Documentation

Documentation lives in:

Documentation contributions follow the same development process as code contributions.

Security Vulnerabilities

Please do not file security vulnerabilities to the public issue tracker. Report them privately to plandev_support@jpl.nasa.gov.

When reporting, please include:

  • Severity assessment
  • Any known workarounds
  • Return contact information for follow-up