GitHub

GCN consists of several open-source projects grouped into the nasa-gcn GitHub organization. These include:

• gcn.nasa.gov: This web site
• gcn-schema: The GCN Notices unified schema
• gcn-kafka-python, gcn-kafka-js: Kafka client libraries
• gcn-classic-to-kafka, gcn-email, gcn-monitor: Backend services
• americana-stack: US Web Design System project template

To contribute to any project in the nasa-gcn GitHub organization, follow these steps:

• Setting up Git

• Forking a Repository

• Cloning a Repository

• Creating a Branch

• Submitting Pull Requests

Setting up Git

You will need to install Git on your development machine. Check out the official installation instructions.

We recommend checking out this guide on adding an SSH key to your github account.

Forking a Repository

Navigate to the repository page for whichever project you wish to contribute to, for example: gcn.nasa.gov.

Click the Fork button.

Click Create Fork to create a new repository in your account.

Cloning a Repository

With your new fork now created, click the Code button and copy the URL in the SSH tab.

Open a terminal window and run the following

git clone <your copied repo url>

Creating a Branch

In a terminal, set your current working directory to the cloned directory and run the following to create and switch to a new branch for your code changes:

git checkout -b <your branch name>

To stage your changes:

git add .

Create a new local commit and add a descriptive comment:

git commit -m "Your descriptive comment"

Push your commits out to your remote fork:

git push

Commit Message Style guide

Please follow these guidelines when writing your commit message. These guidelines are drawn from the Git project itself, a GitLab blog post on Git best practices, and GitKraken's documentation on writing good commit messages.

• Your commit message should consist of a one-line summary followed by an optional long description.

• The summary should be 50 characters or less in length. (Why 50 characters? So that long lines are not truncated when listing commits in the --pretty=oneline format on a standard 80-character wide console.)

• The summary should be an imperative sentence, in the present tense, but without ending puncutation.

• If you include the optional long description, it should be separated from the summary by a blank line.

• The long description should consist of complete sentences.

• The long description should be word-wrapped so that lines are at most 72 characters in length. (Why 72 characters? So that long lines are not truncated when viewing the output of git log on a standard 80-character wide console.)

• Explain what the change does in the simplest and clearest way possible. Ask yourself: would you understand your commit message if you read it a year later? Would someone else understand your commit message without you there to explain it to them?

• Check your description for spelling or grammatical errors.

• You may use any GitHub supported MarkDown syntax to enrich your commit messages with styled text.

Here is an example of a well-formatted commit message:

Increase size of GCN Circulars detail arrows

With the browser's default size for arrows in HTML
`<details>`/`<summary>` elements, the buttons are difficult to activate
on touch-based mobile devices, especially on the GCN Circulars page
which has many of these elements in a list. Add custom CSS to increase
their sizes for better usability.

Submitting Pull Requests

Once you have completed your changes on your branch, create a pull request.

To create a pull request, navigate to your fork in your own github repository. Click the "Branches" link in the upper left hand secondary nav menu. On the next page, click the "New pull request" button for the branch you would like to use. Fill in the title and description, then click the "Create pull request" button on the lower left hand side to create the pull request.

Working With Issues

We use GitHub issues to track bugs and feature requests. To submit a new issue, navigate to the appropriate nasa-gcn repository and click on Issues.

Click New Issue and fill out the form. Please include a concise and descriptive title and as much relevant information in the comment as possible. If relevant, include steps to reproduce, screenshots, error messages, and anything else that may be helpful for us or others to pinpoint the cause of an issue.