Skip to content

Commit

Permalink
Add pre-commit hook scripts and update contributors guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@lesserwhirls
lesserwhirls committed Sep 6, 2019
1 parent 0d35899 commit a9d3ab3
Show file tree
Hide file tree
Showing 4 changed files with 130 additions and 40 deletions.
129 changes: 89 additions & 40 deletions CONTRIBUTING.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,72 +3,73 @@ image::http://www.unidata.ucar.edu/images/logos/thredds_tds-150x150.png[THREDDS]
= Welcome contributors!

First off, thank you for your interest in contributing to the THREDDS project!
This repository contains the code for both netCDF-Java and the THREDDS Data Server (TDS) projects.
The other projects held under the THREDDS umbrella are link:https://github.com/unidata/rosetta[Rosetta] and the latest addition, link:https://github.com/unidata/siphon[Siphon] (a python interface to the TDS).
This repository contains the code for THREDDS Data Server (TDS).
The other three projects held under the THREDDS umbrella are link:https://github.com/unidata/tds[netCDF-Java], link:https://github.com/unidata/rosetta[Rosetta] and the latest addition, link:https://github.com/unidata/siphon[Siphon] (a python data access library, which includes an interface to the TDS).

== Process Overview

* link:#gh-setup[GitHub Setup]
** link:#gh-join[Join Github!]
** link:#gh-fork[Fork the Unidata THREDDS project]
** link:#gh-pull-ud-thredds[Pull down local copy of the Unidata THREDDS project]
** link:#gh-pull-personal-thredds[Add and pull down a local copy of your THREDDS project fork]
* link:#gh-contrib-workflow[Contribution workflow]
** link:#gh-sync-ud[Make sure you have the latest changes from Unidata THREDDS repository]
** link:#gh-branch[Make a new branch for your work and start hacking]
** link:#gh-history-cleanup[Clean up your git commit history]
** link:#gh-final-commit-for-pr[Push changes to your fork to use for the pull request]
** link:#gh-pr[Make the pull request]
* link:#gh-now-what[Now what?]
* link:#gh-setup[GitHub Setup]
** link:#gh-join[Join Github!]
** link:#gh-fork[Fork the Unidata TDS project]
** link:#gh-pull-ud-ncj[Pull down local copy of the Unidata TDS project]
** link:#gh-pull-personal-ncj[Add and pull down a local copy of your TDS project fork]
* link:#gh-contrib-workflow[Contribution workflow]
** link:#gh-sync-ud[Make sure you have the latest changes from Unidata TDS repository]
** link:#gh-branch[Make a new branch for your work and start hacking]
** link:#gh-style-guidelines[Follow these Java Style Guidelines]
** link:#gh-history-cleanup[Clean up your git commit history]
** link:#gh-final-commit-for-pr[Push changes to your fork to use for the pull request]
** link:#gh-pr[Make the pull request]
* link:#gh-now-what[Now what?]

[[gh-setup]]
== GitHub Setup

[[gh-join]
=== Join Github!
To get started contributing to the THREDDS project, the first thing you should do is link:https://github.com/join[sign up for a free account on GitHub].
To get started contributing to a THREDDS project, the first thing you should do is link:https://github.com/join[sign up for a free account on GitHub].

[[gh-fork]
=== Fork the Unidata THREDDS project
Once you have an account, go ahead and link:https://github.com/unidata/thredds#fork-destination-box[fork] the THREDDS project.
By forking the project, you will have a complete copy of the THREDDS project, history and all, under your personal account.
This will allow you to make pull requests against the Unidata THREDDS repository, which is the primary mechanism used to add new code to the project (even Unidata developers do this!).
=== Fork the Unidata netcdf-java project
Once you have an account, go ahead and link:https://github.com/unidata/tds#fork-destination-box[fork] the TDS project.
By forking the project, you will have a complete copy of the TDS project, history and all, under your personal account.
This will allow you to make pull requests against the Unidata TDS repository, which is the primary mechanism used to add new code to the project (even Unidata developers do this!).

[[gh-pull-ud-thredds]
=== Pull down local copy of the Unidata THREDDS project
[[gh-pull-ud-ncj]
=== Pull down local copy of the Unidata TDS project
After cloning the Unidata repository, you can pull down the source code to your local machine by using git:

`git clone --origin unidata [email protected]:Unidata/thredds.git` (for ssh)
`git clone --origin unidata [email protected]:Unidata/tds.git` (for ssh)

or

`git clone --origin unidata https://github.com/Unidata/thredds.git` (for http)
`git clone --origin unidata https://github.com/Unidata/tds.git` (for http)

Note that these commands reference the Unidata repository.

Normally in git, the remote repository you clone from is automatically named `origin`.
To help with any confusion when making pull requests, this commands above rename the remote repository to `unidata`.


[[gh-pull-personal-thredds]
=== Add and pull down a local copy of your THREDDS project fork
[[gh-pull-personal-ncj]
=== Add and pull down a local copy of your TDS project fork

Next, move into the source directory git has created, and add your personal fork of the THREDDS code as a remote"
Next, move into the source directory git has created, and add your personal fork of the TDS code as a remote"

`git clone --origin me [email protected]:<my-github-user-name>/thredds.git` (for ssh)
`git clone --origin me [email protected]:<my-github-user-name>/tds.git` (for ssh)

or

`git clone --origin me https://github.com/,my-github-user-name>/thredds.git` (for http)
`git clone --origin me https://github.com/,my-github-user-name>/tds.git` (for http)

Now you are all set!

[[gh-contrib-workflow]]
== Contribution workflow

[[gh-sync-ud]]
=== Make sure you have the latest changes from Unidata THREDDS repository
First, make sure you have the most recent changes to the THREDDS code by using git pull:
=== Make sure you have the latest changes from Unidata TDS repository
First, make sure you have the most recent changes to the TDS code by using git pull:

`git pull unidata master`

Expand All @@ -95,6 +96,54 @@ If you would like these changes to be stored on your personal remote repository,

Once you are satisfied with your work, there is one last step to complete before submitting the pull request - clean up the history.

[[gh-style-guidelines]]
=== Follow these Java Style Guidelines

We are using the
link:https://google.github.io/styleguide/javaguide.html[Google Java Style Guide] with these exceptions and augmentations:

1. The recommended line width is 120, not 100. Modern screens are much wider than tall, so having
wider lines allows more code to fit on a screen.

2. As a rule, dont add empty javadoc that has no information that can't be seen directly in the
code. For example, do not do this:

```java
/**
* _more_
*
* @param nds _more_
* @param v _more_
* @return _more_
* @throws IOException
*/
protected Foo makeFoo(NetcdfDataset nds, VariableSimpleIF v) throws IOException
```

Better to not have any javadoc then to have empty javadoc. Of course, best is to
put actual, useful comments to help others understand your API.

To assist in following the style, we provide both IntelliJ and Eclipse style files.
These files can be found in the root directory of the repository. If you are not using
an IDE, you can check the style using:

```bash
./gradlew spotlessCheck
```

and you can apply the style using:

```bash
./gradlew spotlessApply
```

It can be easy to forget to run this command before pushing your changes to github. For that,
we have created git pre-commit hook scripts for you to use. The pre-commit hook will run
the spotlessApply task before the commit is made, ensuring that you have the proper code
format. To install the pre-commit hook in a *nix environment (linux, *BSD, MacOS, Cygwin, etc.),
copy the file `hooks/pre-commit-nix` to `.git/hooks/pre-commit` and make it executable.
On windows, copy the file `hooks/pre-commit-windows` to `.git/hooks/pre-commit`.

[[gh-history-cleanup]]
=== Clean up your git commit history

Expand Down Expand Up @@ -193,7 +242,7 @@ Once you have and exit, you will have a change to change the commit message for

```bash

Really cool feature or bug fix. Addresses the github issue Unidata/thredds#1
Really cool feature or bug fix. Addresses the github issue Unidata/tds#1

#Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
Expand All @@ -218,11 +267,11 @@ commit 805b4723c4a2cbbed240354332cd7af57559a1b9
Author: Sean Arms <[email protected]>
Date: Thu Oct 15 09:59:23 2015 -0600

Really cool feature or bug fix. Addresses the github issue Unidata/thredds#1
Really cool feature or bug fix. Addresses the github issue Unidata/tds#1

```

Note that the commit contains the text `Unidata/thredds#1`.
Note that the commit contains the text `Unidata/tds#1`.
This is a cool github trick that will allow you to reference GitHub issues within your commit messages.
When viewed on github.com, this will be turned into a hyperlink to the issue.
While not every contribution will address an issue, please use this feature if your contribution does!
Expand All @@ -239,20 +288,20 @@ However, the rebase has changed the history of your local branch, which means yo
Finally, go to your personal remote repository on github.com and switch to your `mywork` branch.
Once you are on your work branch, you will see a button that says "Pull request", which will allow you to make a pull request.

The github pull request page will allow you to select which repository and branch you would like to submit the pull request to (the `base fork`, which should be `Unidata/thredds`, and `base`, which should be `master`), as well as the `head fork` and `compare` (which should be `<github-user-name/thredds>` and `mywork`, respectively).
The github pull request page will allow you to select which repository and branch you would like to submit the pull request to (the `base fork`, which should be `Unidata/tds`, and `base`, which should be `master`), as well as the `head fork` and `compare` (which should be `<github-user-name/tds>` and `mywork`, respectively).
Once this is setup, you can make the pull request.

[[gh-now-what]]
== Now what?

The Unidata THREDDS project is setup such that automated testing for all pull requests is done via TravisCI.
The Unidata TDS project is setup such that automated testing for all pull requests is done via TravisCI.
The status of the tests can be seen on the pull request page.
For example, see link:https://github.com/Unidata/thredds/pull/231[Unidata/thredds#231] by selecting the `View Details` button.
This pull request was tested on link:https://travis-ci.org/Unidata/thredds/builds/84433104[TravisCI] and passed on all versions of Java supported by the current master branch.
We have setup the THREDDS repository such that changes that do not pass these tests cannot be merged.
For example, see link:https://github.com/Unidata/tds/pull/31[Unidata/tds#31] by selecting the `View Details` button.
This pull request was tested on link:https://travis-ci.com/Unidata/tds/builds/123781062[TravisCI] and passed on all versions of Java supported by the current master branch.
We have setup the TDS repository such that changes that do not pass these tests cannot be merged.

One of the Unidata THREDDS team members will work with you to make sure your work is ready for merging once the tests have passed on TravisCI.
One of the Unidata TDS team members will work with you to make sure your work is ready for merging once the tests have passed on TravisCI.
Note that as changes to your pull request may be required, you can simply push those changes to your personal GitHub repository and the pull request will automatically be updated and new TravisCI tests will be initiated.

If your pull request addresses a bug, we kindly ask that you include a test in your pull request.
If you do not know how to write tests in Java, we will be more than happy to work with you!
If you do not know how to write tests in Java, we will be more than happy to work with you!
20 changes: 20 additions & 0 deletions hooks/pre-commit-nix
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
#!/usr/bin/env bash

# pre-commit hook based on that used by the Uber project NullAway
# https://github.com/uber/NullAway/blob/a5cdecba0e33eed5c8dd86f43bc2cc6408e6fd37/config/hooks/pre-commit

set -e

REPO_ROOT_DIR="$(git rev-parse --show-toplevel)"

FILES=$((git diff --cached --name-only --diff-filter=ACMR | grep -Ei "\.java$") || true )
if [ ! -z "${FILES}" ]; then
echo "Check and apply (if needed) the code style to these staged java files:"
for FILE in $FILES; do
echo " $FILE"
done
COMMA_SEP_FILES=$(echo "$FILES" | paste -s -d "," -)
"${REPO_ROOT_DIR}/gradlew" spotlessApply -Pfiles="$COMMA_SEP_FILES" &>/dev/null
echo "...the code is spotless! :-)"
git add $(echo "$FILES" | paste -s -d " " -)
fi
4 changes: 4 additions & 0 deletions hooks/pre-commit-windows
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
#!/bin/sh
echo
exec powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\hooks\pre-commit.ps1"
exit
17 changes: 17 additions & 0 deletions hooks/pre-commit.ps1
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# pre-commit hook based on that used by the Uber project NullAway (ported to PowerShell by sarms)
# https://github.com/uber/NullAway/blob/a5cdecba0e33eed5c8dd86f43bc2cc6408e6fd37/config/hooks/pre-commit

$REPO_ROOT_DIR = git rev-parse --show-toplevel

$FILES = git diff --cached --name-only --diff-filter=ACMR | Select-String -Pattern "\.java$"

if (-Not ($FILES -eq $null)) {
'Check and apply (if needed) the code style to these staged java files:'
$FILES | foreach {
write-output " $_"
}
$COMMA_SEP_FILES = ($FILES -join ",")
./gradlew spotlessApply -Pfiles=""$COMMA_SEP_FILES"" 2>&1 | Out-Null
write-output "...the code is spotless! :-)"
git add $FILES
}

0 comments on commit a9d3ab3

Please sign in to comment.