Code Contribution Tutorial & ChecklistΒΆ

Below is a step-by-step tutorial for you to follow if you want to contribute new code to the framework effort.

  • The steps below assume you have made a personal fork of the official OpenMDAO-Framework repository. If you have not yet done this, go to https://github.com/OpenMDAO/OpenMDAO-Framework and click on the Fork button in the upper right. You should only have to do this once!

  • Also, if you have not done so yet, clone the official OpenMDAO-Framework repository. You should really only need to do this once. You can do it multiple times–but you’ll use a lot more space and waste time waiting for it to download.

    git clone git@github.com:OpenMDAO/OpenMDAO-Framework.git

    or, if you have trouble connecting, try:

    git clone http://github.com/OpenMDAO/OpenMDAO-Framework.git
  • Finally, if you haven’t done this already, you can save some typing by defining a remote branch in your local repo. Again, you have to do this just once, which is why it’s included here rather than below. Use your GitHub username; in this example it’s hschilling.

    From your local OpenMDAO-Framework repo, type:

    git remote add myfork git@github.com:hschilling/OpenMDAO-Framework.git

You can now follow this checklist for changing code that will get merged into the official OpenMDAO repository (assuming the maintainers approve the change).

  1. Go to the directory containing the local repository.

    cd OpenMDAO-Framework
  2. The next step is to bring your local dev branch up to date with the official one.

    git checkout dev
    git pull origin dev
  3. Now that your local dev is up to date, you can make a new branch.

    git branch <your_branch>
    git checkout <your_branch>
  4. If you’re using the same repo you’ve used before, to be safe you should delete the devenv directory that got built the last time.

    rm -rf devenv
  5. Rebuild the devenv directory with the following script.

    python go-openmdao-dev.py
  6. Activate the environment.

    First, change to the devenv directory.

    cd devenv

    If you’re on Linux, you must be running bash to activate the virtual environment. If you’re not running it, to start it, type:

    bash
    

    Next, if you’re on Linux or OS X, type the following:

    . bin/activate

    If you’re on Windows, type:

    Scripts\activate
  7. Make changes to the code and update the tests. (For more information, see Adding New Tests.)

  8. It’s a good idea to run pylint to check for any bugs in your code. If you do not have pylint on your system, you can install and run it by typing:

    easy_install pylint
    pylint <file_name>

    Fix any errors that pylint found.

  9. Run all the tests to make sure everything still works. (Remember that you must be in an active environment to run the test and docs scripts. So, if you interrupted work and logged out, be sure to reactivate your environment.)

    openmdao test

    Fix any errors found during testing.

  10. Change the docs if needed. (For more information on creating or updating docs, see Documenting OpenMDAO.)

    To build and then display the docs, use the following scripts:

    openmdao build_docs
    openmdao docs
  11. Test the docs.

    openmdao test_docs

    Note: The doctests are automatically run whenever you run openmdao test. Step 11 builds and tests only the docs.

    Fix errors if any.

  12. If you have not done so, visually inspect the docs using the default browser.

    openmdao docs
  13. Now merge out from the latest dev to your branch.

    git pull origin dev
  14. After a successful merge out, run the full test suite again on your branch.

  15. Stage the updated content for the next commit.

    git add .

    (If you’ve been working on your branch for any length of time, you’ve probably already been staging and committing files.)

  16. Commit the staged content. (The -a will include any changes that you forgot to explicitly add to the staging area with git add.)

    git commit -am "Type a short commit message identifying story or code you changed."
  17. Push your changes up to your personal OpenMDAO fork:

    git push myfork <your_branch>
  18. Issue a pull request, i.e., ask the OpenMDAO maintainers to merge your changes:

  • Go to your personal OpenMDAO-Framework fork on GitHub, for example:

    https://github.com/hschilling/OpenMDAO-Framework

  • On the left side of the page, you’ll see an icon and the text branch: followed by a branch name. If you are not on the desired branch, click on the down arrow next to display a list of your branches; then select the one you want merged.

  • Click on the Pull Request button towards the top middle of the page.

  • Fill out the form that appears and then click the Send pull request button.

    The openMDAO maintainers will be notified, and one of them will review your pull request. In the upper middle of the screen is a field that automatically shows your pull requests. You should now show at least 1.

OpenMDAO Home

Previous topic

Appendix: Helpful Git Commands

Next topic

Appendix: Summary of Units

This Page