PDS Git and Github Guide

Getting Started with Github

Instead of reinventing the wheel, there are countless trainings online. Here are few good ones we have found: * Lynda.com: https://www.lynda.com/Git-training-tutorials/1383-0.html * TBD

Notifications

To ensure you are up-to-date with all things happening in repositories, check your notification settings send you emails / mobile notifications when needed. For PDS development, at minimum, please check the following: * Participating: :white_check_mark: Email, :white_check_mark: Web and Mobile * Watching: :white_check_mark: Email, :white_check_mark: Web and Mobile

@mentions Email Filter

Think of a Github @mention as a direct message, versus other issue and commit notifications being group messages. It is highly recommended you setup an email filter to pull out these @mentions (aka direct messages) so you are able to respond in a timely manner.

Here is an example email filter from Microsoft Outlook for Mac:

When a new message arrives that meets all these conditions:
  Body Contains       @my_username
  Subject Contains    "NASA-PDS/" or "NASA-PDS/" or "pds-data-dictionaries/"

Do the following:
  Move to Folder      PDS-@mentions (you may need to create this folder somewhere)

[checked] Do not apply other rules to message that meet the same conditions

[checked] Enabled

Commit Message Best Practices

For commit message best practices, the PDS tries to follow these Github Commit Messages Guidelines where possible.

Once you have read through the guidelines, here are some highlights to touch on and some additional notes:

A properly formed git commit subject line should always be able to complete the following sentence

If applied, this commit will <your subject line here>

  • Rules for a great commit message style

    • Separate subject from body with a blank line

    • Do not end the subject line with a period

    • Capitalize the subject line and each paragraph

    • Use the imperative mood in the subject line

    • Wrap lines at 72 characters

    • Use the body to explain what and why you have done something. In most cases, you can leave out details about how a change has been made.

  • References in commit messages

    • If the commit refers to an issue, add this information to the commit message header or body.

    • See how to autolink references and urls for more information on linking to other issues, repos, commits, etc.

    • Do this for ticket references, people, etc.

    • Be sure use the correct referencing method when going across repositories.

Short (72 chars or less) summary

More detailed explanatory text. Wrap it to 72 characters. The blank
line separating the summary from the body is critical (unless you omit
the body entirely).

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too.
- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space. Use a hanging indent.

For example:

$ git add my_file.txt

# Try to avoid using `git commit -m` unless it is a very trivial update/change
$ git commit

# Vim or Emacs window will open. To change editor that opens, see https://help.github.com/en/github/using-git/associating-text-editors-with-git .
Created new my_file with text in it

This new file includes:
* Part 1
* Part 2
* Part 3

Issue Tracking

See more information at PDS Issue Tracking Guide

Advanced Help

Help With Rebasing

Rebasing can get messy and be painful. We highly recommend reading this article on The Golden Rule of Rebasing.