-
Notifications
You must be signed in to change notification settings - Fork 4
How to Become a Contributor
If you want to contribute to TEDAM project please read this document carefully and follow the steps mentioned.
Take a look at GitHub's excellent help documentation to learn what a pull request is and how to submit one.
Is there already an issue that addresses your concern? Do a bit of searching in the related repository's "GitHub Issues Tab" 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 the development team by submitting an issue. before putting together a pull request. This could save you a lot of time!
If you have not previously done so, please print out and sign the Logo Business Solutions Individual Contribution License Agreement form (LBS ICLA). Note that emailing/postal mailing a signed copy to the project Coordinator is necessary. Upon receiving the form LBS will grant you necessary permissions on the GitHub system.
When you've completed LBS ICLA submission, simply add the following in a comment on your pull request:
I have signed and agree to the terms of the Logo Business Solutions Individual Contributor License Agreement.
Please add the statement above to all future pull requests as well, simply so the TEDAM team knows immediately that this process is complete.
At any given time, TEDAM' master branch represents the version currently under development. For example, if 1.1.1 was the latest TEDAM release, master represents 1.2.0 development, and the 1.1.x branch represents 1.1.2 development.
Create your topic branch to be submitted as a pull request from master. The Development team will consider your pull request for backporting to maintenance versions (e.g. 1.1.2) on a case-by-case basis; you don't need to worry about submitting anything for backporting.
Branches used when submitting pull requests should preferably be named according to issues, e.g. 'INTEXT-1234'. Otherwise, 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.
Please carefully follow the whitespace and formatting conventions already present in the framework.
- Tabs, not spaces
- Unix (LF), not dos (CRLF) line endings
- Eliminate all trailing whitespace
- Wrap Javadoc at 90 characters
- Aim to wrap code at 90 characters, but favor readability over wrapping
- Preserve existing formatting; i.e. do not reformat code for its own sake
- Search the codebase using
git grepand other tools to discover common naming conventions, etc. - Latin-1 (ISO-8859-1) encoding for Java sources; use
native2asciito convert if necessary
/*
* Copyright 2014-2019 Logo Business Solutions
* (a.k.a. LOGO YAZILIM SAN. VE TIC. A.S)
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package ...;Always check the date range in the license header. For example, if you've modified a file in 2018 whose header still reads
* Copyright 2014-2017 Logo Business Solutions
* (a.k.a. LOGO YAZILIM SAN. VE TIC. A.S)then be sure to update it to 2018 appropriately
* Copyright 2014-2018 Logo Business Solutions
* (a.k.a. LOGO YAZILIM SAN. VE TIC. A.S)e.g.
/**
* ...
*
* @author First Last
* @since 3.2
* @see ...
*/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, e.g.
package org.TEDAM.render;
/**
* Unit tests for SPR-8954, in which a custom {@link InstantiationAwareBeanPostProcessor}
* forces the predicted type of a FactoryBean, effectively preventing retrieval of the
* bean from calls to #getBeansOfType(FactoryBean.class). The implementation of
* {@link AbstractBeanFactory#isFactoryBean(String, RootBeanDefinition)} now ensures
* that not only the predicted bean type is considered, but also the original bean
* definition's beanClass.
*
* @author Chris Beams
*/
public class Spr8954Tests {
@Test
public void cornerSpr8954() {
// ...
}
}Use git rebase --interactive, git add --patch and other tools to "squash" multiple commits into atomic changes. In addition to the man pages for git, there are many resources online to help you understand how these tools work. Here is one: http://book.git-scm.com/4_interactive_rebasing.html.
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, as submitted against the LBS ICLA:
Author: First Last <[email protected]>
This helps ensure traceability against the LBS ICLA, and also goes a long way to ensuring useful output from tools like git shortlog and others.
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 for local repository only by omitting the '--global' flag.
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: SPR-1234
- Use imperative statements in the subject line, e.g. "Fix broken Javadoc link"
- Begin the subject line sentence with a capitalized verb, e.g. "Add, Prune, Fix, Introduce, Avoid, etc"
- Do not end the subject line with a period
- Keep the subject line to 50 characters or less if possible
- Wrap lines in the body at 72 characters or less
- Mention associated jira issue(s) at the end of the commit comment, prefixed with "Issue: " as above
- In the body of the commit message, explain how things worked before this commit, what has changed, and how things work now
For examples of this style you can review several such commits:
https://github.com/SpringSource/spring-framework/commit/08e2669b84ec0faa2f7904441fe39ac70b65b078 https://github.com/SpringSource/spring-framework/commit/1d9d3e6ff79ce9f0eca03b02cd1df705925575da
See https://github.com/TEDAM/#building_from_source for instructions. Make sure that all tests pass prior to submitting 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:
- Explain your use case. What led you to submit this change? Why were existing mechanisms in the project insufficient? Make a case that this is a general-purpose problem and that yours is a general-purpose solution, etc
- Add any additional information and ask questions; start a conversation, or continue one from
- Mention the issue ID
- Also mention that you have submitted the LBS ICLA as described above
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.
Add a comment to the associated issue(s) linking to your new pull request.
The TEDAM team takes a conservative approach to accepting contributions to the project. 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 TEDAM 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.