Skip to content

Commit

Permalink
Fix nasa#490, Update Contributing.md CLA links
Browse files Browse the repository at this point in the history 
Elevate CLA section to 3rd-level header and add new sub sections for
separate Framework and Apps CLAs.

Update PDF hyperlinks to be relative instead of absolute.

Reorganize, fix, and add links in issue tracker link list

Add Table of Contents
  • Loading branch information
@astrogeco
astrogeco committed May 26, 2022
1 parent ef24f13 commit e8412de
Showing 1 changed file with 142 additions and 62 deletions.
204 changes: 142 additions & 62 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,40 +2,65 @@

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 at the very least we'll respond to you.

## Table of Contents
[Code of Conduct](#code-of-conduct)

[Ways to Contribute](#ways-to-contribute)
* [Report Bugs](#report-bugs)
* [Feature Requests](#feature-requests)
* [Security Vulnerabilities](#security-vulnerabilities)
* [Pull Requests](#pull-requests)
* [Discussions and Questions](#discussions-and-questions)

[Writing High-Quality Code](#writing-high-quality-code)

[Quick Links to Submodules](#quick-links-to-submodules)

## Code of Conduct
<!-- vscode-markdown-toc -->
* [Code of Conduct](#CodeofConduct)
* [Ways to Contribute](#WaystoContribute)
* [Discussions and Questions](#DiscussionsandQuestions)
* [Report Bugs](#ReportBugs)
* [Before Submitting a Bug](#BeforeSubmittingaBug)
* [Reporting a Bug](#ReportingaBug)
* [Once a bug is submitted:](#Onceabugissubmitted:)
* [Feature Requests](#FeatureRequests)
* [Before Submitting a Feature Request](#BeforeSubmittingaFeatureRequest)
* [Submitting a Feature Request](#SubmittingaFeatureRequest)
* [Once a feature request is submitted:](#Onceafeaturerequestissubmitted:)
* [Security Vulnerabilities](#SecurityVulnerabilities)
* [Contributor License Agreement (CLA)](#ContributorLicenseAgreementCLA)
* [cFS-Framework CLA](#cFS-FrameworkCLA)
* [cFS-Apps CLA](#cFS-AppsCLA)
* [Pull Requests](#PullRequests)
* [Create a Pull Request](#CreateaPullRequest)
* [Once a Pull Request Ready for Review](#OnceaPullRequestReadyforReview)
* [How to Squash Commits](#HowtoSquashCommits)
* [How to Amend Commits](#HowtoAmendCommits)
* [Writing High-Quality Code](#WritingHigh-QualityCode)
* [Using GitHub Actions Workflows](#UsingGitHubActionsWorkflows)
* [View Failed Workflows](#ViewFailedWorkflows)
* [View Workflow Results](#ViewWorkflowResults)
* [Configure Workflows](#ConfigureWorkflows)
* [cFS Workflows](#cFSWorkflows)
* [Issue Trackers for cFS Components](#IssueTrackersforcFSComponents)
* [Issue Trackers for Framework Components](#IssueTrackersforFrameworkComponents)
* [Lab apps](#Labapps)
* [Tools](#Tools)
* [Issue Trackers for other cFS Apps](#IssueTrackersforothercFSApps)

<!-- vscode-markdown-toc-config
numbering=false
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->

## <a name='CodeofConduct'></a>Code of Conduct

This project and everyone participating in it is governed by the [cFS Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the [product team](README.md#contact-the-cfs-product-team).

## Ways to Contribute
## <a name='WaystoContribute'></a>Ways to Contribute

### Discussions and Questions
### <a name='DiscussionsandQuestions'></a>Discussions and Questions

For discussions, questions, or ideas, [start a new discussion](https://github.com/nasa/cFS/discussions/new) in the cFS repository under the Discussions tab.

[Join the cfs community mailing list](README.md#join-the-mailing-list).


### Report Bugs
### <a name='ReportBugs'></a>Report Bugs

#### Before Submitting a Bug
#### <a name='BeforeSubmittingaBug'></a>Before Submitting a Bug
1. Perform a cursory search to see if the bug has already been reported. For issues in each submodule, visit the section [Quick Links to Submodules](#quick-links-to-submodules). 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](https://github.com/nasa/cFS/issues/new?assignees=&labels=&template=bug_report.md&title=).

#### Reporting a Bug
#### <a name='ReportingaBug'></a>Reporting a Bug

If you run into a bug with the project:
1. Open an issue using the bug report template.
Expand All @@ -47,51 +72,73 @@ If you run into a bug with the project:
7. Provide any additional context if applicable.
8. Provide your full name or GitHub username and your company organization if applicable.

#### Once a bug is submitted:
#### <a name='Onceabugissubmitted:'></a>Once a bug is submitted:
1. The project 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.

### Feature Requests
#### Before Submitting a Feature Request
### <a name='FeatureRequests'></a>Feature Requests
#### <a name='BeforeSubmittingaFeatureRequest'></a>Before Submitting a Feature Request
1. Review the cFS README.md file 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, visit the section [Quick Links to Submodules](#quick-links-to-submodules). 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](https://github.com/nasa/cFS/issues/new?assignees=&labels=&template=feature_request.md&title=).

#### Submitting a Feature Request
#### <a name='SubmittingaFeatureRequest'></a>Submitting a Feature Request
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.

#### Once a feature request is submitted:
#### <a name='Onceafeaturerequestissubmitted:'></a>Once a feature request is submitted:
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.

### Security Vulnerabilities
### <a name='SecurityVulnerabilities'></a>Security Vulnerabilities
Please view our [Security Policy](https://github.com/nasa/cFS/security/policy) for more information.

### Pull Requests
#### Ready to Add Your Code?
### <a name='ContributorLicenseAgreementCLA'></a>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](mailto:GSFC-SoftwareRelease@mail.nasa.gov) and copy [cfs-program@lists.nasa.gov](mailto: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.

#### <a name='cFS-FrameworkCLA'></a>cFS-Framework CLA

For contributions to the cFS-Framework repositories: [cFE](https://github.com/nasa/cFE), [osal](https://github.com/nasa/osal), [psp](https://github.com/nasa/psp), or submodules in the [apps](apps), [libs](libs), and [tools](tools) directories.

- [cFS-Framework Corporate CLA](cFS_Framework_Corporate_CLA.pdf)

- [cFS-Framework Individual CLA](cFS_Framework_Individual_CLA.pdf)

#### <a name='cFS-AppsCLA'></a>cFS-Apps CLA

For contributions to the cFS Apps repositories [BP](https://github.com/nasa/bp), [CF](https://github.com/nasa/cf), [CS](https://github.com/nasa/cs), [DS](https://github.com/nasa/ds), [FM](https://github.com/nasa/fm), [HK](https://github.com/nasa/HK/), [HS](https://github.com/nasa/HS/), [LC](https://github.com/nasa/LC/), [MD](https://github.com/nasa/MD/), [MM](https://github.com/nasa/MM/), [SC](https://github.com/nasa/SC)

- [cFS-Apps Corporate CLA](cFS_Apps_Corporate_CLA.pdf)

- [cFS-Apps Individual CLA](cFS_Apps_Individual_CLA.pdf)

### <a name='PullRequests'></a>Pull Requests

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

Follow GitHub's fork-branch-pull request pattern.
1. Fork the relevant cFS component (eg. cfe, osal, psp).

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

3. Submit a pull request to the nasa `main` branch. 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.

4. Add commits to your branch. For information on commit messages, review [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). Please follow commit message convention:

```
Fix #XYZ, SHORT_DESCRIPTION
LONG_DESCRIPTION (optional)
```
#### Contributor License Agreement (CLA)
Sign and email the appropriate Contributor License agreement below to GSFC-SoftwareRelease@mail.nasa.gov and copy cfs-program@lists.nasa.gov
* Corporate Contributor License agreement : https://github.com/nasa/cFS/blob/main/Corp_CLA_GSC-18719-1%20cFS%20Bootes.pdf
* Individual Contributor License agreement : https://github.com/nasa/cFS/blob/main/Individual_CLA_GSC-18719-1%20cFS%20Bootes.pdf
#### <a name='CreateaPullRequest'></a>Create a Pull Request

#### Create a Pull Request
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.
Expand All @@ -100,7 +147,7 @@ Sign and email the appropriate Contributor License agreement below to GSFC-Softw
6. Provide any additional context if applicable.
7. Provide your full name or GitHub username and your company or organization if applicable.

#### Once a Pull Request Ready for Review
#### <a name='OnceaPullRequestReadyforReview'></a>Once a Pull Request Ready for Review
1. Verify the commit message and PR title uses the template `Fix #XYZ, SHORT_DESCRIPTION`. For information on commit messages, review [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/). The commit message may use the template:
```
Fix #XYZ, SHORT_DESCRIPTION
Expand All @@ -113,7 +160,7 @@ LONG_DESCRIPTION (optional)
4. The project team will label the issue and evaluate the pull request in the weekly configuration control board (CCB) meeting. For more information, visit [The cFS CCB Process](https://github.com/nasa/cFS/wiki/The-cFS-CCB-Process).
5. If the pull request is accepted, it will be merged into cFS.

#### How to Squash Commits
#### <a name='HowtoSquashCommits'></a>How to Squash Commits

##### Interactive Rebase

Expand Down Expand Up @@ -203,30 +250,37 @@ git branch -m -f ${new_branch} ${old_branch}
git push --force
```

#### How to Amend Commits
#### <a name='HowtoAmendCommits'></a>How to Amend Commits

1. To modify your last commit message:

```sh
git commit --amend
```

2. 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:

```sh
git push --force
```

1. To change the actual content of your last commit, stage those changes:

```sh
git add <file>
git add <files-to-amend>
```
2. Amend the commit:

```sh
git commit --amend
```
3. Now the last commit is replaced by your new and improved commit. Push the commit:

```sh
git push --force
```

## Writing High-Quality Code
## <a name='WritingHigh-QualityCode'></a>Writing High-Quality Code

1. Follow cFS code conventions (formatting, symbol naming, file naming, etc). Do *not* change/reformat existing code, except to address your changes.
- The cFS submodules use the Format Check workflow to ensure users follow the [clang-format-10](https://github.com/nasa/cFS/blob/main/.clang-format) style. For more information on how to use the Format Check workflow, view [Using GitHub Actions Workflows](#using-github-actions-workflows).
Expand All @@ -245,23 +299,24 @@ git push --force
- Review these workflows for any warnings or errors.
- Once successful, create a pull request.

### Using GitHub Actions Workflows
### <a name='UsingGitHubActionsWorkflows'></a>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
#### <a name='ViewFailedWorkflows'></a>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
#### <a name='ViewWorkflowResults'></a>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.
Expand All @@ -273,34 +328,59 @@ or
2. 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, expand Code scanning alerts at the bottom of the list of checks and select CodeQL.

#### Configure Workflows
#### <a name='ConfigureWorkflows'></a>Configure Workflows

1. Workflows are under [.github/workflows](https://github.com/nasa/cFS/tree/main/).
2. Configure the files as needed. For more information on how to configure GitHub Actions, visit [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions).

#### Our Workflows
#### <a name='cFSWorkflows'></a>cFS Workflows

Information on our GitHub Action Workflows can be found in the [.github/workflows README.md](https://github.com/nasa/cFS/tree/main/.github/workflows/README.md) document.

## Quick Links to Submodules
Before you [report bugs](#report-bugs) or submit [feature requests](#feature-requests), search through the open issues in each submodule to ensure that your ticket is relevant, not redundant, nor in conflict with other tickets:
* [cFS Bundle Issues](https://github.com/nasa/cfs/issues)
* [cFE Issues](https://github.com/nasa/cfe/issues)
* [OSAL Issues](https://github.com/nasa/osal/issues)
* [PSP Issues](https://github.com/nasa/psp/issues)

### Apps
* [ci_lab Issues](https://github.com/nasa/ci_lab/tree/296d12cde4f90d112d1578cb584ddae200a2d282)
* [sample_app Issues](https://github.com/nasa/sample_app/issues)
* [sample_lib Issues](https://github.com/nasa/sample_lib/issues)
* [sch_lab Issues](https://github.com/nasa/sch_lab/tree/882846bb778432c8780555b9d4bef45535584174)
* [to_lab Issues](https://github.com/nasa/to_lab/tree/031de3dde3f5265e98d7cd2bc154d93bee8520b0)

### Tools
* [cFS-GroundSystem Issues](https://github.com/nasa/cFS-GroundSystem/issues)
* [elf2cfetbl Issues](https://github.com/nasa/elf2cfetbl/tree/6762b1c3b455665dae57e35f14a50fe327830391)
* [tblCRCTool Issues](https://github.com/nasa/tblCRCTool/tree/b02864ba56b12e00ab152225e3e8f9d6c039d48c)
## <a name='IssueTrackersforcFSComponents'></a>Issue Trackers for cFS Components

Before you [report bugs](#report-bugs) or submit [feature requests](#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 Bundle](https://github.com/nasa/cfs/issues)


### <a name='IssueTrackersforFrameworkComponents'></a>Issue Trackers for Framework Components

- [cFE](https://github.com/nasa/cfe/issues)
- [OSAL](https://github.com/nasa/osal/issues)
- [PSP](https://github.com/nasa/psp/issues)

#### <a name='Labapps'></a>Lab apps

- [ci_lab](https://github.com/nasa/ci_lab/issues)
- [sample_app](https://github.com/nasa/sample_app/issues)
- [sample_lib](https://github.com/nasa/sample_lib/issues)
- [sch_lab](https://github.com/nasa/sch_lab/issues)
- [to_lab](https://github.com/nasa/to_lab/issues)

#### <a name='Tools'></a>Tools

- [cFS-GroundSystem](https://github.com/nasa/cFS-GroundSystem/issues)
- [elf2cfetbl](https://github.com/nasa/elf2cfetbl/tree/6762b1c3b455665dae57e35f14a50fe327830391)
- [tblCRCTool](https://github.com/nasa/tblCRCTool/tree/b02864ba56b12e00ab152225e3e8f9d6c039d48c)

### <a name='IssueTrackersforothercFSApps'></a>Issue Trackers for other cFS Apps

- [BP](https://github.com/nasa/bp/issues)
- [CF](https://github.com/nasa/cf/issues)
- [CS](https://github.com/nasa/cs/issues)
- [DS](https://github.com/nasa/ds/issues)
- [FM](https://github.com/nasa/fm/issues)
- [HK](https://github.com/nasa/HK//issues)
- [HS](https://github.com/nasa/HS//issues)
- [LC](https://github.com/nasa/LC//issues)
- [MD](https://github.com/nasa/MD//issues)
- [MM](https://github.com/nasa/MM//issues)
- [SC](https://github.com/nasa/SC/issues)


0 comments on commit e8412de

Please sign in to comment.