Skip to content

Latest commit

 

History

History
404 lines (292 loc) · 20.4 KB

CONTRIBUTING.md

File metadata and controls

404 lines (292 loc) · 20.4 KB
Raw

Core Flight System Contributing Guide

So you'd like to contribute to cFS? Below are some guidelines for contributors to follow. Contributions come in all shapes and sizes. We appreciate your help with documentation, unit tests, framework code, continuous-integration, or simply reporting bugs and improvement ideas. We can't promise that we'll accept every suggestion or fix every bug in a timely manner but we'll respond to you as quickly as possible.

Code of Conduct

This project and everyone participating in it is governed by the cFS Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the product team.

Ways to Contribute

Discussions and Questions

For discussions, questions, or ideas, start a new discussion in the cFS repository under the Discussions tab. If you prefer email, you can also join the cfs community mailing list.

Security Vulnerabilities

Please view our Security Policy for more information.

Bug Reports

Before Reporting a Bug

  1. Perform a cursory search to see if the bug has already been reported. For issues in each submodule, check the issue trackers in the relevant cFS component/submodule. If a bug has been reported and the issue is still open, add a comment to the existing issue instead of opening a new one.
  2. Determine which repository the bug should be reported in. If you are not sure, place the issue in NASA/cFS.

Reporting a Bug

If you find a bug in our code don't hesitate to report it:

  1. Open an issue using the bug report template.
  2. Describe the issue.
  3. Describe the expected behavior if the bug did not occur.
  4. Provide the reproduction steps that someone else can follow to recreate the bug or error on their own.
  5. If applicable, add code snippets or references to the software.
  6. Provide the system the bug was observed on including the hardware, operating system, and versions.
  7. Provide any additional context if applicable.
  8. Provide your full name or GitHub username and your company organization if applicable.

What Happens to my Bug Report?

  1. The cFS team will label the issue.
  2. A team member will try to reproduce the issue with your provided steps. If the team is able to reproduce the issue, the issue will be left to be implemented by someone.

New Feature Requests

cFS has a multitude of users from different fields and backgrounds. We appreciate your ideas for enhancements!

Before Requesting a New Feature

  1. Review the cFS README to see if your feature is in the major future work.
  2. Perform a cursory search to see if the feature has already been requested. For issues in each submodule, check the issue trackers in the relevant cFS component/submodule. If a feature request has been reported and the issue is still open, add a comment to the existing issue instead of opening a new one.
  3. Determine which repository the feature should be reported in. If you are not sure, place the issue in NASA/cFS.

Requesting a New Feature

  1. Open an issue using the feature request template.
  2. Describe the feature.
  3. Describe the solution you would like.
  4. Describe alternatives you've considered.
  5. Provide any additional context if applicable.
  6. Provide your full name or GitHub username and your company organization if applicable.

What Happens to my Feature Request?

  1. The project team will label the issue.
  2. The project team will evaluate the feature request, possibly asking you more questions to understand its purpose and any relevant requirements. If the issue is closed, the team will convey their reasoning and suggest an alternative path forward.
  3. If the feature request is accepted, it will be marked for implementation.

Issue Trackers for cFS Components

Before you report bugs or submit feature requests, search through the open issues in each submodule to ensure that your ticket is relevant, not redundant, nor in conflict with other open or pull requests issues:

If your bug or feature hasn't been reported or requested before, create a new issue in the appropriate repository. If you find a similar issue, please add a comment on it with your experience or input.

Please ensure that your name is associated with your github profile before contributing.

For issues related to continuous testing workflows or multi-component "epics" start at the "framework bundle"

cFS-Framework Components

Lab Apps

Tools

Other cFS Apps

Pull Requests

Contributor License Agreement (CLA)

Before your code can be merged into our repositories, we require a contributor license agreement (CLA) for individual and corporate contributors. You can submit this by downloading, signing, and emailing the appropriate form to GSFC-SoftwareRelease@mail.nasa.gov and copy cfs-program@lists.nasa.gov.

Currently we have separate forms for the Framework repositories and the Apps. See the sections below to know which one to submit. We plan on combining these in the future.

cFS-Framework CLA

For contributions to the cFS-Framework repositories: cFE, osal, psp, or submodules in the apps, libs, and tools directories.

cFS-Apps CLA

For contributions to the cFS Apps repositories BP, CF, CS, DS, FM, HK, HS, LC, MD, MM, SC, SCH

Before starting your Pull Request

Ready to Add Your Code? Follow GitHub's fork-branch-pull request pattern.

  1. Fork the relevant cFS component (eg. cfe, osal, psp).

  2. Find the related issue number or create an associated issue that explains the intent of your new code.

  3. Create a new branch in your fork to work on your fix. We recommend naming your branch fix-ISSUE_NUMBER-<FIX_SUMMARY>.

  4. Add commits to your branch. For information on commit messages, review How to Write a Git Commit Message and our git commit guidelines.

Creating a Pull Request

We recommend creating your pull-request as a "draft" and to commit early and often so the community can give you feedback at the beginning of the process as opposed to asking you to change hours of hard work at the end.

  1. For the title, use the title convention Fix #XYZ, SHORT_DESCRIPTION.
  2. Describe the contribution. First document which issue number was fixed using the template "Fix #XYZ". Then describe the contribution.
  3. Provide what testing was used to confirm the pull request resolves the link issue. If writing new code, also provide the associated coverage unit tests.
  4. Provide the expected behavior changes of the pull request.
  5. Provide the system the bug was observed on including the hardware, operating system, and versions.
  6. Provide any additional context if applicable.
  7. Provide your full name or GitHub username and your company or organization if applicable.
  8. Verify that the PR passes all workflow checks. If you expect some of these checks to fail. Please note it in the Pull Request text or comments.

What Happens to My Pull Request?

  1. The cFS team will label and evaluate the pull request in the weekly configuration control board meeting.
  2. If the pull request is accepted, it will be merged into cFS.

Writing High-Quality Code

  1. Follow cFS code conventions (formatting, symbol naming, file naming, etc). Do not change or reformat existing code, except to address your changes.

  2. For new APIs, add unit tests to cover nominal and off-nominal conditions.

  3. Add or expand stub functions for the unit test codebase when adding or modifying functions.

  4. If changing existing APIs, update the unit tests to cover these changes and remove tests that are no longer relevant.

  5. Review the static code analyses results from the Static Analysis and CodeQL Analysis workflows. For more information on how to use these workflows, view Using GitHub Actions Workflows.

    • Push code changes to the appropriate forked repository.
    • Go to the Actions tab and enable GitHub Actions Workflow. The CodeQL Analysis and Static Analysis will be triggered for all pushed code.
    • Review these workflows for any warnings or errors.
    • Once successful, create a pull request.

Using GitHub Actions Workflows

Several of our GitHub Actions Workflows are used to ensure pushed code and pull requests do not break cFS, create vulnerabilities, and follow our code conventions. Other workflows are used for documentation purposes.

Most of the workflows in the NASA/cFS repository will run for all branches when code is pushed and a pull request is created, except for the changelog workflow that runs manually.

All of our workflows will be available for forked repositories once enabled. To enable workflows, navigate to the Actions tab and click "I understand my workflows, go ahead and enable them".

View Failed Workflows

  1. Navigate to Actions in the selected repository. For newly forked repositories, enable workflows after clicking on Actions.
  2. In the left sidebar, click the workflow you want to view.
  3. From the list of workflow runs, click the name of the run you want to see.
  4. Under Jobs or in the visualization graph, click the failed job.
  5. Any failed steps are automatically expanded to display the results.

View Workflow Results

  1. Navigate to Actions in the selected repository. For newly forked repositories, enable workflows after clicking on Actions.
  2. In the left sidebar, click the workflow you want to view.
  3. From the list of workflow runs, click the name of the run you want to see.
  4. Scroll to the bottom of the page and download the artifacts. For CodeQL results, navigate to the Security Tab and click Code scanning alerts. CodeQL results will only be available on your forked repository.

or

  1. In pull requests, click the Checks tab.
  2. From the list of workflow runs, click the name of the run you want to see.
  3. Scroll to the bottom of the page and download the artifacts. For CodeQL results, expand Code scanning alerts at the bottom of the list of checks and select CodeQL.

Configure Workflows

  1. Workflows are under .github/workflows.
  2. Configure the files as needed. For more information on how to configure GitHub Actions, visit Workflow syntax for GitHub Actions.

cFS Workflows

The cFS testing workflows are found in .github/workflows you can read a summary in the that directory's README.

Git Commit Guidelines

  1. Please follow commit message convention. This format links github issues to pull requests with code and helps us to deliver high-quality documentation. The format-check workflow will also alert you when your commits or pull request do not match the format below.
Fix #XYZ, SHORT_DESCRIPTION

LONG_DESCRIPTION (optional)

  1. Verify there is a single commit message per topic. For a good example, see this multi-topic pull request.

  2. Squash or amend the commit messages as needed.

Working with git commits

The following sections are short "How-Tos" on techniques that can help you edit your commits to better match our format guidelines.

How to Squash Commits
Interactive Rebase
  1. Switch to the main branch and ensure you are up to date:
git checkout main && git pull
  1. Checkout your feature branch:
git merge feature_branch
  1. Use rebase to open the vi or other editor that lists the commits:
git rebase main -i
  1. A text editor will open with a file that lists all the commits in your branch, and in front of each commit is the word "pick". It looks something like this:
pick 1fc6c95 do something
pick 6b2481b do something else
pick dd1475d changed some things
pick c619268 fixing typos
  1. For every line except the first, you want to replace the word "pick" with the word "squash" or with "f". "squash" merges the commit into previous commit. "f" is like "squash", but discard this commit's log message. So, if you wish to skip the step where you have to update the commit message then use "f". To edit the first commit message, replace "pick" with "r". For example, it should look like this:
pick 1fc6c95 do something
squash 6b2481b do something else
squash dd1475d changed some things
squash c619268 fixing typos

or

r 1fc6c95 do something
f 6b2481b do something else
f dd1475d changed some things
f c619268 fixing typos

  1. Save and close the file. If you used "pick" and "squash", a new file should pop up in your editor, combining all the commit messages of all the commits. Reword this commit message as you want, and then save and close that file as well.

  2. Push the commit:

git push --force
Soft Reset

Use the "soft" method with caution. Ensure that you reset back to the original baseline. If you have switched branches and pulled from the remote since starting the branch originally, you may inadvertently overwrite other changes.

  1. To tell Git to reset HEAD to another commit, so index and the working directory will not be altered in any way use a soft reset. All of the files changed between the original HEAD and the commit will be staged. To use a soft reset:
git reset --soft main
  1. Add all changes:
git add -A
  1. Add a commit message:
git commit -m "Fix #XYZ, SHORT_DESCRIPTION

LONG_DESCRIPTION (optional)"
  1. Push the commit:
git push --force
Replace Branch

This method had no chances of inadvertently overwriting other stuff.

  1. Make a new branch with a new name at the current main:
git checkout -b "fix-ISSUE_NUMBER-<FIX_SUMMARY>".
  1. Merge:
git merge --squash ${old_branch}
  1. Test the result, then commit to write a new commit message summarizing the full change:
git commit
  1. Rename your new branch over your old branch to replace it:
git branch -m -f ${new_branch} ${old_branch}
  1. Push to GitHub:
git push --force
How to Amend Commits
  1. To modify your last commit message:
git commit --amend
  1. The previous commit message will load an editor session, where you can make changes to the message, save those changes and exit. When you save and close the editor, the editor writes a new commit containing that updated commit message and makes it your new last commit. Push the new changes:
git push --force
  1. To change the actual content of your last commit, stage those changes:
git add <files-to-amend>
  1. Amend the commit:
git commit --amend
  1. Now the last commit is replaced by your new and improved commit. Push the commit:
git push --force