All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome.
If you are simply looking to start working with the UV-CDAT codebase, navigate to the GitHub "issues" tab and start looking through interesting issues.
Feel free to ask questions on mailing list or askbot
Bug reports are an important part of making UV-CDAT more stable. Having a complete bug report will allow others to reproduce the bug and provide insight into fixing. Since many versions of UV-CDAT are supported, knowing version information will also identify improvements made since previous versions. Often trying the bug-producing code out on the master branch is a worthwhile exercise to confirm the bug still exists. It is also worth searching existing bug reports and pull requests to see if the issue has already been reported and/or fixed.
Bug reports must:
-
Include a short, self-contained Python snippet reproducing the problem. You can have the code formatted nicely by using GitHub Flavored Markdown:
```python >>> import vcs >>> vcs.init() ... ``` -
Explain why the current behavior is wrong/not desired and what you expect instead.
The issue will then show up to the UV-CDAT community and be open to comments/ideas from others.
Now that you have an issue you want to fix, enhancement to add, or documentation to improve, you need to learn how to work with GitHub and the UV-CDAT code base.
To the new user, working with Git is one of the more daunting aspects of contributing to UV-CDAT. It can very quickly become overwhelming, but sticking to the guidelines below will make the process straightforward and will work without much trouble. As always, if you are having difficulties please feel free to ask for help.
The code is hosted on GitHub. To contribute you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on the project.
Some great resources for learning Git:
- the GitHub help pages.
- the NumPy documentation.
- Matthew Brett's Pydagogue.
GitHub has instructions for installing Git, setting up your SSH key, and configuring Git. All these steps need to be completed before working seamlessly with your local repository and GitHub.
If you have write access to the main UV-CDAT repository, then just create a branch there. If you don't, you can create your fork of UV-CDAT by going to the UV-CDAT project page and hitting the fork button. You will want to clone your fork to your machine: (HTTPS or SSH is preferred to git:// for security reasons).
git clone git://github.com/UV-CDAT/uvcdat.git UV-CDAT-yourname
cd UV-CDAT-yourname
git remote add myuvcdat git@github.com:your-user-name/uvcdat.git
This creates the directory UV-CDAT-yourname and connects your repository to both the upstream (main project) UV-CDAT repository and your new fork.
You want your changes to appear in separate pull requests, so remember to create a separate feature branch for changes. For example:
git branch shiny-new-feature
git checkout shiny-new-feature
The above can be simplified to:
git checkout -b shiny-new-feature
This changes your working directory to the shiny-new-feature branch. Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to UV-CDAT. You can have many shiny-new-features and switch in between them using the git checkout command.
Before making your code changes, it is often necessary to build the code that was just checked out. The best way to develop UV-CDAT is to build using default settings:
mkdir uvcdat-build
cmake uvcdat-path-to-source
make -jN
If you're not the developer type, contributing to the documentation is still of huge value. You don't even have to be an expert on UV-CDAT to do so! Something as simple as pointing out missing information or broken links will be of great value.
UV-CDAT uses the flake8 tool to check the style of your code.
Please try to maintain backward-compatibility. UV-CDAT has lots of users with lots of existing code, so avoid breaking their workflow if at all possible. If you think breakage is required, clearly state why as part of the Pull Request. Also, be careful when changing method signatures and add deprecation warnings where needed.
UV-CDAT is serious about Test-driven Development (TDD). This development process "relies on the repetition of a very short development cycle: first the developer writes an (initially failing) automated test case that defines a desired improvement or new function, then produces the minimum amount of code to pass that test." So, before actually writing any code, you should write your tests. Often the test can be taken from the original GitHub issue. However, it is always worth considering additional use cases and writing corresponding tests.
Adding tests is one of the most common requests after code is pushed to UV-CDAT. It is worth getting in the habit of writing tests ahead of time so this is never an issue.
All tests should go into the tests subdirectory of the specific package. There are many examples already around and you can simply look at these for inspiration.
The testing.checkimage module has a special check_result_image() function
that make it easy to check whether a plot produced after data extraction and
transformation is equivalent to baseline. For an example see below:
import cdms2, sys, vcs, os
src = sys.argv[1]
pth = os.path.join(os.path.dirname(__file__), "..")
sys.path.append(pth)
import checkimage
x = vcs.init()
x.drawlogooff() # It is important to disable logo for testing
f = cdms2.open(vcs.prefix + "/sample_data/clt.nc")
s = f("clt",slice(0, 1), squeeze=1)
b = x.createboxfill()
b.level_1 = 0.5
b.level_2 = 14.5
x.plot(s, b, bg=1)
fnm = "test_boxfill_lev1_lev2.png"
x.png(fnm)
ret = checkimage.check_result_image(fnm, src, checkimage.defaultThreshold)
sys.exit(ret)
The tests can then be run directly inside your build tree (directory) by typing:
ctest
To save time and run tests in parallel
ctest -jN
The tests suite is exhaustive and takes around 20 minutes to run. Often it is worth running only a subset of tests first around your changes before running the entire suite. This is done by using one of the following constructs:
ctest -R test-name
ctest -R regex*
Keep style fixes to a separate commit to make your PR more readable. Once you've made changes, you can see them by typing:
git status
If you've created a new file, it is not being tracked by Git. Add it by typing:
git add path/to/file-to-be-added.py
Doing 'git status' again should give something like:
# On branch shiny-new-feature
#
# modified: /relative/path/to/file-you-added.py
#
Finally, commit your changes to your local repository with an explanatory message. An informal commit message format is in effect for the project. Please try to adhere to it. Here are some common prefixes along with general guidelines for when to use them:
- ENH: Enhancement, new functionality
- BUG: Bug fix
- DOC: Additions/updates to documentation
- TST: Additions/updates to tests
- BLD: Updates to the build process/scripts
- PERF: Performance improvement
- CLN: Code cleanup
The following defines how a commit message should be structured. Please reference the relevant GitHub issues in your commit message using GH1234 or #1234. Either style is fine, but the former is generally preferred:
- a subject line with < 50 chars
- one blank line
- optionally, a commit message body (72-char).
Now you can commit your changes in your local repository:
git commit -a
or
git commit -a -m "Message here"
After having worked on your branch for a while, you might want to combine or reorder some of them to get a cleaner history (and thus, a cleaner pull request). To do that, you can use the interactive rebase feature:
git rebase -i HEAD~#
where # is the number of commits you want to combine. Then you can pick the relevant commit message and discard others (or use the other commands; refer to the help at the bottom of the buffer).
When you want your changes to appear publicly on your GitHub page, push your forked feature branch's commits:
git push myuvcdat shiny-new-feature
Here myuvcdat is the name given to your own GitHub fork, if you followed the previous instructions. You can list the remote repositories with:
git remote -v
which should display something like:
origin git://github.com/UV-CDAT/uvcdat.git
myuvcdat git@github.com:yourname/uvcdat.git
Now your code is on GitHub, but it is not yet a part of the UV-CDAT project. For that to happen, a Pull Request needs to be submitted on GitHub.
When you're ready to ask for a code review, you will file a Pull Request. Before you do, again make sure you've followed all the guidelines outlined in this document regarding code style, tests, and documentation. You should also double check your branch changes against the branch it was based off of:
- Navigate to your repository on GitHub--https://github.com/your-user-name/uvcdat.
- Click on Branches.
- Click on the Compare button for your feature branch.
- Select the base and compare branches, if necessary. This will be master and shiny-new-feature, respectively.
If everything looks good you are ready to make a Pull Request. A Pull Request is how you make your changes available to us for review, so that we can discuss it and ultimately merge it into the main line of development that will become the next release. To submit a Pull Request:
- Navigate to your repository on GitHub.
- Click on the Pull Request button.
- You can then click on Commits and Files Changed to make sure everything looks okay.
- Write a description of your changes in the Preview Discussion tab.
- Click Send Pull Request.
This request can then be discussed with the community and be approved by the repository maintainers. If you need to make more changes, you can make them in your branch, push them to GitHub, and the pull request will be automatically updated:
git push myuvcdat shiny-new-feature
This will automatically update your Pull Request with the latest code and restart the Travis-CI tests.
Once your feature branch is accepted into upstream, you'll probably want to get rid of the branch. You can first update your local copy of the "master" branch, in which your changes have hopefully been merged:
git fetch origin
git checkout master
git reset --hard origin/master
Then you can do:
git branch -d shiny-new-feature
Make sure you use a lower-case -d, or else Git won't warn you if your feature branch has not actually been merged.
The branch will still exist on GitHub, so to delete it there do:
git push origin --delete shiny-new-feature