CONTRIBUTING.md

Contributing to SolarPILOT

You can contribute to SolarPILOT by letting us know about problems or suggesting new features, or by making your own changes or additions to the code. You may want to help us fix an issue someone else reported, fix an issue you discovered, or add a new feature to SolarPILOT.

Let us know about a problem or suggest a new feature

If you find a problem with SolarPILOT, or would like to request a new feature, let us know by submitting an issue.

If you have a question about using SolarPILOT, you can ask us at SolarPILOT support.

Contribute code to the SolarPILOT project

If you are ready to contribute code to SolarPILOT, there are a couple of things you should know first:

• First off, please read SolarPILOT's Contribution Policy. In particular, you'll need to send us an email (to solarpilot.support@nrel.gov) that states:

I agree to contribute to SolarPILOT. I agree to the following terms and conditions for my contributions: First, I agree that I am licensing my contributions under the terms of the current SolarPILOT license. Second, I agree that, in order to conform to any future open source software license(s) under which SolarPILOT may be provided, the terms of my license may be modified without any notice to me and without my consent. Third, I represent and warrant that I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes my contributions, I represent and warrant that I have received permission to make contributions and grant the required license on behalf of my employer.

• SolarPILOT consists of several code repositories, so you will need to determine where to make your contribution. For example, if you are making a change to the way SolarPILOT's heliostat positioning algorithm model makes a calculation, you would work with the SSC repository. If you are adding a new feature that changes both calculations and the user interface, like adding a new layout algorithm, then you would work with both the SolarPILOT repository and the SSC repository. If you need help figuring out where your contribution should go, please let us know.

• We use GitHub to manage the open source project, so you will need to learn how to use it to fork, clone, branch, check out, pull, add, commit, and push your work.

Instructions

Here are the steps that will prepare you to contribute code to SolarPILOT:

1. Install GitHub on your computer.
2. Follow the instructions on the SolarPILOT wiki to clone the SolarPILOT repositories and build SolarPILOT.
3. Create a fork on github.com for the repository (SolarPILOT, SolTrace, SSC, LK, or WEX) you are contributing to.
4. Clone your fork to create a local copy on your computer.
5. Follow the best practices steps to contribute your code.

Best practices

The Git VCS is most effective when new development occurs in a branch and the proposed code changes are submitted via a pull request into one of the main branches. The repository is configured to require special steps to be taken when contributing to one of the protected branches. This helps maintain stable releases and ensure new content conforms with the goals of the project.

The repository is organized into several branches, and some have special importance. The approach generally follows the model outlined here.

Branch	Access	Description	Branch from	Merge from	Merge to
master	admin	Current stable version	---	patch, release	---
develop	SolarPILOT-RW	Bleeding edge development version	---	feature, patch, release	---
patch	Contributors	Hotfixes for current major.minor release	Master @tag	---	master, develop, patch
release	SolarPILOT-RW	Next release version	develop	patch	master, develop
feature-<name>	Contributors	All new development	develop, feature-<other>	develop, feature-<other>	develop, feature-<other>

The following steps should be taken when contributing code.

1. Determine the branch to which your code should apply.

   • Bug fixes for the existing release should start from the master branch with HEAD at the latest relevant version tag.
   • Bug fixes that don't affect the current release should start from develop.
   • New features should start from develop or a sub-branch.

2. If you have a bug fix, create an Issue on the issue tracker. Label the issue with needs-patch and the milestone for the next version to which it should apply. Fixes in develop should use the milestone for the next major.minor.0 release, while patches should use the existing major.minor.patch+1 tag.

3. checkout the appropriate branch or tag.

4. Create and checkout a new branch for your changes. git checkout -b <new branch name>.

5. Make your changes and commit them to your branch with frequent, descriptive commits.

6. Build SolarPILOT and test it to make sure your code works as expected (see below).

7. git push origin <new branch name> to publish your branch.

8. On the repository web page, create a pull request for your new branch.

   • Specify the target branch according to the selection from step (1) above.
   • Make sure to fully comment your pull request.
   • The project admins will review your pull request and solicit discussion if any issues arise. If your pull request is accepted, the branch will be deleted, and you can delete your local copy of the branch. If the request is not accepted, please review the discussion to determine and resolve any issues.

Resources for Learning GitHub

If you are new to GitHub, you can find helpful articles to help you learn how it works on the web. Some examples are:

• Using the Fork-and-Branch Git Workflow from Scott's Weblog is a good introduction.

• Git Concepts: Branches, Forks, and Pull Requests from Will Anderson is useful, although the video on the page does not work.

• 3.2 Git Branching - Basic Branching and Merging from the Git documentation.

• Fork a Repo from GitHub Help.

• About pull requests from GitHub Help.

Test Protocol

We are in the process of setting up a Google Test framework for testing your contribution to ensure that it does not cause any problems with the software.

For now, you can help to ensure that your code works with the rest of SolarPILOT by:

1. Compiling SolarPILOT with your contribution for Windows, Mac, and Linux.

2. Fixing any compiler warning messages.

3. Running the compiled program with several configurations.

For example, if you made a change to how the heliostat layout algorithm works, you should test layout, flux simulation, and optimization runs with different heliostat configurations, numbers of heliostat templates, and spacing requirements.

Note that a change to SSC may affect performance in projects that also use SSC, such as SDKTool and SAM. Changes to the code should be tested within each project that uses the modified library. Please refer to the list of project dependencies for more information.