Skip to content

Latest commit

 

History

History
329 lines (244 loc) · 12.2 KB

CONTRIBUTING.md

File metadata and controls

329 lines (244 loc) · 12.2 KB

MATPOWER Contributors Guide

Getting Involved

MATPOWER is a community effort and your involvement is greatly appreciated. We are always looking for help in identifying and fixing bugs, writing test cases, improving documentation, answering queries on the mailing lists, enhancing existing functionality and implementing new features that fit within the general scope of the project.

Please take a moment to review this document before contributing, as it helps to communicate your respect for the time and efforts of the MATPOWER developer community managing and developing this open source project.

Repository Organization

This repository, for the MATPOWER core distribution, is organized in the following directories:

  • data - MATPOWER case files
  • docs - PDF version of User's Manuals and other documentation
  • lib - software that implements MATPOWER's core functions
  • mips - MIPS subrepository, with code in it's own lib subdirectory
  • most - MOST subrepository, with code in it's own lib subdirectory
  • mptest - MP-Test subrepository, with code in it's own lib subdirectory

The subrepositories are included in the core MATPOWER repository using git subrepo. This means these sub-projects have their own repositories to host their respective code development and issue tracking, but they do not need any special treatment when working with the MATPOWER repository. In this context they are just like any other files.

Mailing Lists

Your participation is welcomed on the two mailing lists for MATPOWER users and developers, MATPOWER-L and MATPOWER-DEV-L, respectively. We can always use help in answering questions from newer users.

Reporting a Bug

The issue tracker is the preferred channel for reporting bugs or submitting code changes (pull requests). A good bug report is extremely helpful and benefits the entire community, so if you find a bug, including a mistake in the documentation, please report it.

  1. Confirm it is a bug. You should be able to demonstrate that it is an error caused by the code in this repository. If it is simply that you do not understand a result you are getting, ask a question on the discussion mailing list instead of submitting an issue (after searching the archives to see if your question has already been answered, of course).

  2. Check if it has already been reported or fixed. Make sure the bug still exists by attempting to reproduce it using the latest master branch in the repository. Search the issues on GitHub to make sure it has not already been reported.

  3. Isolate the problem. Create a reduced test case with no external dependencies, if possible, that demonstrates the problem, so others can easily reproduce it. The simpler the case the better.

  4. Submit an issue that includes a detailed report. A good bug report will avoid the need for the developers to track you down for more information.

    • Use an accurate, descriptive title for your issue.
    • Describe your environment - better yet, include the output of mpver on your system.
    • Include a few lines of code or attach a script file that reproduces the bug.
    • Describe the result you got and what you expected.
    • Select "bug" under "Labels".

Note: Bugs or issues related to one of the sub-projects, MIPS, MOST or MP-Test should be submitted to the issue tracker for the respective sub-project, not to the main MATPOWER issue tracker.

Reviewing Issues

If you see an issue or bug report submitted by someone else, please consider helping out by attempting to reproduce the issue on your system. Report your experience in a comment on the issue. Even if you are not comfortable submitting a patch to fix it, any information you can add to help the developers locate a solution is greatly appreciated. Simply leave your comments on the issue. The same goes for review of pull requests, which are discussed below.

Submitting Additions or Modifications to the Code

Code contributions are a great help and are always welcome. This includes bug fixes, enhancements to existing functionality, new features or tests, and even edits to the included documentation. It is always a good idea to discuss your ideas first on the developer mailing list, especially for larger or more complex contributions.

Contributions should be submitted as pull requests, as described below. Before submitting your pull request, please make sure you have tested your changes and that they follow the MATPOWER developer guidelines.

Getting started

Step 1 : Set Up Git.

Make sure git knows your name and email address:

git config --global user.name "Random Citizen"
git config --global user.email "[email protected]"

Step 2 : Fork the repository.

Click "Fork" on the repository page on GitHub to create your own fork of the project.

Step 3 : Clone

Check out your copy locally and configure the remotes:

# clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/matpower.git
# go to the newly cloned directory
cd matpower
# assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/MATPOWER/matpower.git

Making your changes

Step 4 : Update

If it has been a while since you first made your clone, get all of the latest changes from the upstream repository:

git checkout master
git pull upstream master

Step 5 : Branch

Create a new topic branch where you can work on your new feature, change or fix. Always create it from an up-to-date master branch:

git checkout -b <topic-branch-name>

Step 6 : Commit

Edit your local copy of the files to implement your feature, change or fix. Then commit your changes in logical chunks. Do not combine multiple logical changes in a single commit. And please adhere to the guidlines below for commit messages.

Add and commit:

git add my/changed/files
git commit

Writing good commit messages is important. A commit message should describe what changed and why. Follow these guidelines when writing one:

  1. The first line should be 50 characters or less and contain a short description of the change. Begin with a capitalized imperative verb, for example, "Fix issue #4", not "Fixed issue #4" or "Fixes issue #4". All other words in this description should be in lowercase with the exception of proper nouns, acronyms, and references to code, such as function or variable names.
  2. Keep the second line blank.
  3. Wrap all other lines at 72 columns.

If your patch fixes an open issue, the issue should be referenced in the first line of the commit message with the issue number preceded by a hash symbol (#), e.g. Fix #4, Q limit violations and at the end of the message with the full URL. Use the Fixes: prefix for bug fixes. For other references use Refs:. For example, a good commit message might look something like:

Fix issue #4, Q limit violations in CPF.

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

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, with blank lines in between, but conventions vary here.

- Use a hanging indent

Fixes: https://github.com/MATPOWER/matpower/issues/4
Refs: https://www.mail-archive.com/[email protected]/msg05557.html
Refs: https://github.com/MATPOWER/matpower/pull/5

Step 7 : Test

Bug fixes and features should come with tests, either added to the appropriate existing test function in lib/t, or in a new test function with a descriptive name beginning with t_, in which case it should also be added to test_matpower.m. See the documentation for MP-Test and the existing MATPOWER test files (e.g. t_pf_dc) for examples of how to write tests.

You can run your tests by typing the name of your test function at the MATLAB or Octave prompt, or test_matpower to run the entire test suite.

Sharing your changes

Step 8 : Rebase

Use git rebase (not git merge) to sync your work with the upstream development branch from time to time, and especially before pushing.

git fetch upstream
git rebase upstream/master

And use Git's interactive rebase feature to tidy up your commits, if necessary, before making them public. See this article for some helpful background on git rebase vs. git merge.

Step 9 : Push

Push your topic branch up to your fork on GitHub.

git push origin <topic-branch-name>

Open a pull request against the master branch, by going to the GitHub page for your fork (https://github.com/<your-username>/matpower), and selecting your topic branch. Click the "Pull Request" button and fill out the form using a clear, accurate title and description.

IMPORTANT: By submitting a pull request, you represent that you have the right to license your contribution to PSERC and the community, and agree by submitting the patch that your contributions are licensed under the 3-clause BSD license.

Step 11 : Discuss and update

You will probably get feedback or requests for changes to your pull request. This is a normal part of the submission process, so don't be surprised or discouraged.

To make changes to an existing pull request, make the changes to your branch. When you push that branch to your fork, GitHub will automatically update the pull request. Each time the pull request is updated it triggers a CI (continuous integration) test run which results in a check mark or an X next to the commit on the pull request page and next to the pull request name in the issue tracker, indicating whether or not all tests passed.

After your pull request has been reviewed and approved by a MATPOWER Collaborator, it can be merged into the upstream MATPOWER repository. Once this has happened the pull request is closed and your contributions are part of the project and available to the world! Congratulations and many thanks!

Git Workflow and Branching Model

We use GitHub Flow, meaning that the master branch should always be ready for release and all new work is done in descriptively named branches off of master, which are then reviewed via pull requests. The only addition is that we do still have a release branch that always points to the latest versioned release. We also use tags like 6.0 to tag each release.

Licensing

By submitting a pull request, you represent that you have the right to license your contribution to PSERC and the community, and agree by submitting the patch that your contributions are licensed under the 3-clause BSD license.

Thanks

We would like to express our appreciation to everyone who has contributed to the MATPOWER project and community for helping to make it a useful tool for the power systems community. Thank you!