We are always excited to have contributions from the community, especially from new contributors! There are many different ways that you can make contributions to the Daffodil project, including wiki updates, mailing list support, testing, and new code.
This following steps documents the workflow to get you started with contributing code to Apache Daffodil.
- If you have not done so already, we reccomend you:
- Sign up for an account in JIRA
- Subscribe to the email@example.com mailing list by sending an email to firstname.lastname@example.org and following the instructions.
Send an email to the email@example.com mailing list requesting Jira contributor access. For example:
Once granted, you will be able to assign bugs to yourself and create new bugs.
- Sign up for an account in JIRA
Search for an existing issue or create a new issue in JIRA that represents the change you would like to make or bug to fix.
If you are a beginner to Daffodil development, a good place to start is with the Daffodil beginner bugs.
See the Daffodil Issue Tracker information for creating issues and what information/discussions should take place in JIRA.
- Assign the issue to yourself so others know that you are working on it.
Visit the Apache Daffodil GitHub and create a fork by clicking on "Fork" in the top right.
Clone your new fork. This will be your
Add the ASF upstream repository as a new git remote, calling it asf:
Create a new branch off of the
XYZis the JIRA bug number and
-descriptionis an optional, very short description of the bug making it easier to differentiate between multiple development branches. For example:
Make changes to the branch, frequently adding new commits. For example, the following process should repeat until your code is ready to be reviewed:
When changes are complete, rebase your commits onto the latest
asf/masterand verify that all tests pass:
Note that you should not use
git mergeto sync to the
fetch/rebaseand avoid merge commits. Pull requests containing merge commits will be rejected.
If multiple commits were made in step 7, use
git rebase -i asf/masterto interactively rebase and squash the commits into the smallest number of logical commits. Most commonly this should be a single commit, but there may be some rare cases where multiple commits make sense.
Ensure the commit has an appropriate and descriptive commit message. The first line of a commit message should contain a short (~50 characters) description of the changes. The second line should be blank, followed by a longer description of the change, wrapped at 72 characters. This long description should describe what was changed in the commit and, more importantly, why those changes were made. The 'what' can be determined by inspecting the code, but the 'why' is often less obvious. At the end of the commit should be a blank line followed by a reference to the JIRA bug, e.g. DAFFODIL-123. Multiple bugs referenced in a single commit should be separated by a comma on the same line. An example of a commit message is:
Push your branch to your fork:
- Use the GitHub interface to create a pull request for your new branch.
Wait for review comments. There must be at least two +1's from other committers before the change can be merged. If there are any review comments that require changes or the automated Travis CI build fails, create a new commit on your branch (do not squash your changes yet or use
git commit --amend) and push your branch with new commits to GitHub for furthur review. The process should look like:
The pull request will automatically update with your new commit. Repeat this step until at least two +1's are recieved from committers.
Once at least two +1's are received from committers, a committer can accept the pull request. If you made extra commits in step 12, you should now fetch the latest asf, rebase and squash the changes into a single commit (fixing potential conflicts), and push to
A committer can now merge the pull request using the GitHub GUI. This is to be done by clicking the
"Merge pull request"drop down and selecting
"Rebase and merge". The
"Create merge commit"and
"Squash and merge"options should not be used. For new committers, you may need to link your GitHub and ASF accounts by visiting https://gitbox.apache.org before you can merge.
- The committer that merged the pull request should now mark the JIRA bug as "
Resolved"and add a comment with the git commit hash that includes the fix.
If you would like to clean up, you can now delete your development branch, either via the GitHub user interface or: