Step-by-step Instructions for Bugfix or Feature

Set Up Your Git Environment (for first-time contributors)

Make sure you have your basic Git environment set up.

Choose Something to Work On

Find a bug or feature you like and can manage.  If you wish, file it, or go straight to creating a pull request.  Make sure your pull request follows the guidelines for pull requests.

Design Your Solution (RFEs & complex bugs only)

If you are developing a feature, or you are working on a bug that involves an interface change, you'll need to go through the design phase:

Document your design

If you're working on a feature or a complex bug, document it in the space used for project designs on Confluence.  Create a design document describing your design.  See this example.   Some bugs are small enough that they don't need documenting.  If you are not sure, ask on the development forum. 

Get comments on your design

Initiate a discussion of your idea or bug fix by starting a topic for it on the PBS Pro development forum:

• • Make sure you start your discussion in the Developers category in the forum
  • When you start your topic, use a summary of the feature or bug for your topic title.  For example: Server Periodic Hook
  • In the forum, add a pointer to your design page

After you've started your topic, add an HTML link in your design page on Confluence that points to the discussion topic in the forum

Get review comments from community members about your bug fix or design.  Make sure review comments are solicited and posted in the development forum, and not on the wiki.  All discussion of your design and code should take place on the development forum.

Get approval for your design

For features or complex bugs, get sign-off of the high-level design approach from two people: one maintainer and one other contributor (who can be a maintainer).  If you took a complex feature and broke it down into sub-tasks, and you are working on a sub-task, you need two sign-offs on the design for your sub-task.  Make sure that all approvals are posted in the development forum, not on the wiki.

Make finding information easy

Add a link in the design page containing the EDD that points to the discussion, and vice versa. 

Also add a link from the EDD to the pull request and vice versa.

Develop Your Code and Tests

Bring your local master branch up to date

Update your (forked & locally cloned) repository's master branch with the golden repository's master (IMPORTANT: Your fork's master branch should not be touched with any of your development changes. It should just reflect the golden repository's master, exactly).

Update your fork

Push the updated master branch to your fork:

Create your dev branch

Create a development branch for your bug or feature:

Check the development checklist

Look at the checklist for developing code. 

Write your code and tests

We recommend developing your code and your tests in parallel. 

For large projects, it may help to break down your contribution into smaller, workable pieces.  Code for smaller pieces must follow the guidelines for contributions.

PTL Tests

Write an automated test for every change you make, if that test does not already exist.  Your PTL tests should provide good coverage of the requirements and your design. Take a look at the steps for testing code.

Put license text in headers for code and tests

If you create new source or test files, make sure that this license text is in the header for all code and test files.

Use the commit-push cycle to perfect your code

• Commit changes in the updated file to your branch with a good commit message.  It will be the title of your pull request.  Make your commit message relevant and concise, so that it will be helpful to you later:

Tip: Commit often, perfect later.

• Push the development branch to your fork.  By convention,  'origin' points to your forked repository on GitHub:

• Repeat the above steps until you are satisfied with your code change.

Prepare for creating a pull request

• At the point where you create your pull request, your branch should be up to date with master, and your changes should be in a single commit.  So:
• Fetch changes made to the golden repository by other contributors.  By convention, 'upstream' points to the golden repository on GitHub:

• Rebase your dev branch

• Squash all your commits into ONE SINGLE COMMIT, and write a meaningful commit message for your commit. You can also use git commit --amend or rebase if you'd rather do it separately.  A good commit message is important because it will also be the title of your pull request.

• Finally, push the polished branch to your fork.  If you did a git rebase, you'll need to do a force push.

Create a Pull Request

Your code changes are good to go! Go ahead and create a pull request.  This allows other contributors to review your changes and provide comments. 

Give your pull request a short descriptive title.  The title of your pull request (which comes from the title of your commit message) should summarize the bug/issue as it affects a user/customer.   If you also have an issue, the titles should match.

In your pull request, add a link to the design document and discussion (for features).  If you created an issue, add a link to it.

Add your test logs and other test results to the pull request.

Make sure your pull request follows the guidelines for contributions; if it doesn't, it will not be accepted.

Make your pull request informative.  Follow the guidelines in the pull request template. 

Don't forget about your pull request after you create it – stale pull requests will be closed without warning.

Get Approval for Your Code and Tests

Your code is ready to be merged into the golden repository when the following are true:

• • The code adheres to our coding standards
  • You have approval from two people: one maintainer and one other contributor (who can be a maintainer); approvals for code and tests happen on GitHub inside pull requests, not the wiki

Get Changes Reviewed, and Check Them In

Address review comments from other contributors

Address review comments on your code, making changes to your development branch as necessary

• • Commit new changes to the same development branch on your local machine
  • Push changes to your fork, this will automatically update your pull request on Github

Make reviewing easier

To help reviewers see incremental diffs during the code review process, we recommend that you don't squash again until the code review process is complete

You're done!

Once the maintainers review the pull request, they will merge it in. Congratulations on becoming a contributor to PBS Pro!

Clean Up

• Housekeeping: we strongly recommend that you delete the development branch from your forked and cloned repos now.

Optionally Update Your Issue

If you filed an issue, /wiki/spaces/~agurban/pages/13991979.