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 workflow should be followed by all people that wish to contribute following steps documents the workflow to get you started with contributing code to Apache Daffodil. There are other types of contributors (e.g. wiki, mailing list support, testing) that this does not cover..
- If you do not have a JIRA account, request one by visiting https://selfserve.apache.org/jira-account.html. Once granted, you will be able to assign bugs to yourself and create new bugs.
You may also want to subscribe to the dev@daffodil.apache.org and commits@daffodil.apache.org mailing lists by sending an email to dev-subscribe@daffodil.apache.org and commits-subscribe@daffodil.apache.org, respectively, and following the instructions.
Search for an existing issue or create a new issue Search for an issue in JIRA that represents the change you would like to make or bug to fix. If one does not exist, create a issue.
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 your self. You may need to request permissions to modify the bug by sending an email to dev@daffodil.apache.org
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 using ssh (you will need to create an ssh key and add it to GitHub if you haven't already). This Create a GitHub fork of the Daffodil GitHub mirror and clone it. This remote will be your
origin
remote:Code Block language bash $ git clone https://githubgit@github.com/<username>/incubator-:<github_username>/daffodil.git $ cd daffodil
Add the ASF upstream repository as a new git remote, calling it asf:
Code Block language bash $ git remote add asf https://github.com/apache/incubator-daffodil.git $ git fetch asf
It is also recommended to change the push URL of the asf remote to a nonsense string to prevent accidentally pushing to it--branches should only be pushed to your fork:
Code Block $ git remote set-url --push "push to apache/daffodil disabled"
Create a new branch off of the
asf/mastermain
branch nameddaffodil-XYZ-description,
whereXYZ
is the JIRA bug number and-description
is an optional, very short description of the bug making it easier to differentiate between multiple development branches. For example:Code Block language bash $ git checkout -b daffodil-123-bitorder-feature asf/mastermain
Make changes to the branch, frequently adding new commits. For example, the following process should repeat until your code is ready to be reviewed:
Code Block edit files $ git add <files that have changed> $ git commit
Code changes should follow the Daffodil Code Style Guidelines and should add appropriate tests using the Test Data Markup Language (TDML)
oror unit tests.
Tests insrc/test/scala-debug
that are fixed should be moved intosrc/test/scala
.When changes are complete, rebase your commits onto
asf/master
and verify that all tests pass:
Note that you should not useCode Block language bash $ git fetch asf $ git rebase asf/master $ sbt test
git pull
orgit merge
to sync to theasf
repo. Alwaysfetch/rebase
and avoid merge commits. Pull requests containing merge commits will be rejected.General guidelines for a good commit message:
-
If multiple commits were made,
git rebase -i asf/master
should be used to 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 each commit has an appropriate and descriptive commit message. The first line of a commit message should contain a short (~50 characters) description of the commitchanges.
- 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.
- If there are any changes that deprecate functionality or are non-backwards compatible, a section should follow labeled with the "Deprecation/Compatibility:" keyword with a description that can be copy/pasted into release notes. This should be more user focused, including what was deprecated/non-backwards compatible and a migration guide.
- At the end of the commit should be a blank line followed by a reference to the JIRA bug number, e.g. DAFFODILDAFFODIL-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:
Code Block language textAdd support for the dfdl:bitOrder feature Longer explanation of what changes were made to support the bitOrder feature, including a description of why the changes were made. Multiple lines are wrapped at 72 characters DAFFODIL-123. Deprecation/Compatibility: The dfdlx:bitDirection extension property is now deprecated in favor of the new dfdl:bitOrder property: - dfdlx:bitDirection="l2r" becomes dfdl:bitOrder="mostSignificantBitFirst" - dfdlx:bitDirection="r2l" becomes dfdl:bitOrder="leastSignificantBitFirst" DAFFODIL-123
Info Your IDE or operating system environment may add files to the git repository that are specific to your development environment, such as temporary backups and IDE project files. These files should be ignored and not commited by git. However, because they are specific to your environment, the Daffodil .gitignore file does not contain entires for them. You may want to add such entires to one of the following system-specific gitignore files instead:
$GIT_DIR/info/exclude
$XDG_CONFIG_HOME/git/ignore
$HOME/.config/git/ignore
See the gitignore man page for more information.
When changes are complete, rebase your commits onto the latest
asf/main
and verify that all tests pass:Code Block language bash $ git fetch asf $ git rebase asf/main $ sbt test
Note that you should not use
git pull
orgit merge
to sync to theasf
repo. Alwaysfetch/rebase
and avoid merge commits. Pull requests containing merge commits will be rejected.If multiple commits were made in step 8, use
git rebase -i asf/main
to 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.Push your branch to your fork:
Code Block language bash $ git push origin daffodil-123-bitorder-feature
- Use the GitHub interface to create a pull request for your new branch.
Mark the JIRA bug asPatch Available
. 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:Code Block edit files $ git add <files that changed> $ git commit $ git push origin daffodil-123-bitorder-feature
The pull request will automatically update with your new commit.
ContinueRepeat this
processstep until at least two +1's are recieved from
comitterscommitters.
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 now squash them using
git rebase -i
and fetch the latest asf, rebase and squash the changes into a single commit (fixing potential conflicts), and push toorigin
using the--force
option:Code Block $ git fetch asf $ git rebase -i asf/mastermain $ git push --force origin daffodil-123-bitorder-feature
A committer can now merge the pull request using the GitHub guiGUI. This is to be done by clicking the
"Merge pull request"
dropdown 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 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:
Code Block language bash $ git push --delete origin daffodil-123-bitorder-feature $ git branch -D daffodil-123-bitorder-feature