Contributor Guidelines - Turbots/oraj-360-tool GitHub Wiki

Do you have improvements you would like to contribute to the 360 Tool?

We very highly welcome your pull requests, but we ask that you carefully read this document first to understand how best to submit them.

Understand the basics

Not sure what a pull request is, or how to submit one? Take a look at GitHub's excellent help documentation first.

Browse the issues first; create an issue if necessary

Is there already an issue that addresses your concern? Do a bit of searching in our issue tracker to see if you can find something similar. If not, please create a new issue before submitting a pull request unless the change is truly trivial, e.g. typo fixes, removing compiler warnings, etc.

If you're considering any significant change, we recommend proposing and discussing it with others before putting together a pull request. This could save you a lot of time!

Create your branch from master

At any given time, the master branch represents the version currently under development.

Create your topic branch to be submitted as a pull request from master. We will consider your pull request for backporting to maintenance versions on a case-by-case basis; you don't need to worry about submitting anything for backporting.

Use short branch names

Branches used when submitting pull requests should use succinct, lower-case, dash (-) delimited names, such as 'fix-warnings', 'fix-typo', etc. In fork-and-edit cases, the GitHub default 'patch-1' is fine as well. This is important, because branch names show up in the merge commits that result from accepting pull requests, and should be as expressive and concise as possible.

Submit JUnit test cases for all behavior changes

Search the codebase to find related unit tests and add additional @Test methods within. It is also acceptable to submit test cases on a per issue basis.

Use real name in git commits

Please configure git to use your real first and last name for any commits you intend to submit as pull requests. For example, this is not acceptable:

Author: Nickname <[email protected]>

Rather, please include your first and last name, properly capitalized:

Author: First Last <[email protected]>

You can configure this globally via the account admin area GitHub (useful for fork-and-edit cases); globally with

git config --global user.name "First Last"
git config --global user.email [email protected]

or locally for the oraj-360-tool repository only by omitting the '--global' flag:

git config user.name "First Last"
git config user.email [email protected]

Format commit messages

Please read and follow the commit guidelines section of Pro Git.

Most importantly, please format your commit messages in the following way (adapted from the commit template in the link above):

Short (50 chars or less) summary of changes

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, preceded by a
   single space, with blank lines in between, but conventions vary here

Issue: issue-1234
  1. Use imperative statements in the subject line, e.g. "Fix broken Javadoc link"
  2. Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune, Fix, Introduce, Avoid, etc"
  3. Do not end the subject line with a period
  4. Keep the subject line to 50 characters or less if possible
  5. Wrap lines in the body at 72 characters or less
  6. Mention associated issue(s) at the end of the commit comment, prefixed with "Issue: " as above
  7. In the body of the commit message, explain how things worked before this commit, what has changed, and how things work now

Run all tests prior to submission

Make sure that all tests pass prior to submitting your pull request.

Submit your pull request

Subject line:

Follow the same conventions for pull request subject lines as mentioned above for commit message subject lines.

In the body:

  1. Explain your use case. What led you to submit this change? Why were existing mechanisms in the framework insufficient? Make a case that this is a general-purpose problem and that yours is a general-purpose solution, etc
  2. Add any additional information and ask questions; start a conversation, or continue one from the issue
  3. Mention the issue

Note that for pull requests containing a single commit, GitHub will default the subject line and body of the pull request to match the subject line and body of the commit message. This is fine, but please also include the items above in the body of the request.

Mention your pull request on the associated issue

Add a comment to the associated issue(s) linking to your new pull request.

Expect discussion and rework

We take a very conservative approach to accepting contributions to the framework. This is to keep code quality and stability as high as possible, and to keep complexity at a minimum. Your changes, if accepted, may be heavily modified prior to merging. You will retain "Author:" attribution for your Git commits granted that the bulk of your changes remain intact. You may be asked to rework the submission for style (as explained above) and/or substance. Again, we strongly recommend discussing any serious submissions with the Spring Framework team prior to engaging in serious development work.

Note that you can always force push (git push -f) reworked / rebased commits against the branch used to submit your pull request. i.e. you do not need to issue a new pull request when asked to make changes.