= Suggested GIT workflows

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you 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.

== Avoid git-pull!

git-pull should never get invoked if you have dirty files lying around
or if your branch is ahead of master. This will always lead to some
dirty artifacts in the commit history:

----------------------------------------------------------------------------
Merge branch 'master' of http://git-wip-us.apache.org/deltaspike into master
----------------------------------------------------------------------------


== git pull --rebase


An easy version for getting rid of the auto-merges is using

[source,bash]
--------------------
$ git pull --rebase
--------------------

Please note that this sometimes trashes your working tree if there are
unmergeable files around. Cleaning this up with a forced manual rebase
is not something we would recommend for a git beginner.


=== Working in an own branch


This is actually the suggested way to prevent auto-merges.

Create an own branch where you do your feature work. Either do all your
work in one branch or create one branch per feature you are working on.

[source,bash]
----------------------
$ git branch mybranch
----------------------

After you finished your feature, `git-add` and `git-commit` your work.
Check with `git-status` that you don't have any dirty files and
uncommitted changes around. You can use `git-stash` to 'backup'
unfinished work.

Then switch back to the master branch and pull changes done by other
committers in the meantime.

----------------------
$ git checkout master
$ git pull --rebase
----------------------

You should now get all the changes done by other committers and the will
get applied to your local master branch. Now go back to your private
branch and rebase your locally performed work to the HEAD of master.

------------------------
$ git checkout mybranch
$ git rebase master
------------------------

If you got conflicts, you will get lines with ">>>>" added to those
files. Resolve those conflicts manually, add them and finish the rebase.

Check with `git-status` and `gitk` if the merge went well and the
history now contains your changes. If all is well, go back to the master
branch and merge your changes in.

------------------------------------------------------------------------
$ git pull --rebase     // (just for safety, you should see no changes)
$ git checkout master
$ git merge mybranch
------------------------------------------------------------------------

Finally you can push your changes to the ASF git repo

-----------
$ git push
-----------

== Contribution workflow

Please understand that our contribution workflow is designed for outside contributions.  They should represent your
changes and your changes alone.  Any other contributors should raise their own pull request or submit their own patch.
Committers should continue to follow the discussion flow for complex changes, and merge their changes when ready.

=== Raising Pull Requests

You should use the following workflow if you plan to contribute features or bug fixes to Apache DeltaSpike via GitHub

First, fork our repository https://github.com/apache/deltaspike[on github]

Second, clone it locally and add our upstream as a remote

----------------------
$ git clone https://github.com/<YOUR USERNAME>/deltaspike
$ git remote add asf https://git-wip-us.apache.org/repos/asf/deltaspike.git
----------------------

Third, find a JIRA ticket to work on.  When you do, use that as your branch name

---------------------------------
$ git checkout -b DELTASPIKE-XXX
---------------------------------

Now you can start to work on your patch. When you are finished, commit
your changes. But don't forget to **add the name of the JIRA issue to
the commit message**.

-------------------------------------------------
$ git commit -am "DELTASPIKE-XXX: Fixed some issue"
-------------------------------------------------

Once you're done with your changes, make sure you're up to date and rebase from master

-------------------------------------------------
$ git pull asf master --rebase
-------------------------------------------------

Next, push your branch to GitHub

-------------------------------------------------
$ git push origin DELTASPIKE-XXX
-------------------------------------------------

Finally, raise your PR.  If you go to your GitHub fork of DeltaSpike, you should see an option to create a PR

=== Merging Pull Requests

Whenever a PR gets created for DeltaSpike, an email is sent to the dev@deltaspike.  It will include the subject

-------------------------------------------------
[GitHub] deltaspike pull request #00: DELTASPIKE-XXX some changes
-------------------------------------------------

Which will contain the instructions

-------------------------------------------------
You can merge this pull request into a Git repository by running:

$ git pull https://github.com/<GITHUB USERNAME>/deltaspike DELTASPIKE-XXX
-------------------------------------------------

As long as you don't rebase, pushing the result of this pull will merge the change into our git repository and close the PR.  If there are any issues with the patch, you can monitor the build status from the PR, where we run some smoke tests against the commit to ensure its working.  Please make the requestor aware of any issues identified (e.g. code quality, formatting, missing tests, etc).

=== Creating patches

You should use the following workflow, if you plan to contribute patches or new features to DeltaSpike.

First update you local copy of the repository:

----------------------
$ git checkout master
$ git pull --rebase
----------------------

Then create a new local branch for your work. It's good practice to name it after the corresponding JIRA issue.

---------------------------------
$ git checkout -b DELTASPIKE-XXX
---------------------------------

Now you can start to work on your patch. When you are finished, commit
your changes. But don't forget to **add the name of the JIRA issue to
the commit message**.

-------------------------------------------------
$ git commit -am "DELTASPIKE-XXX: Fixed some issue"
-------------------------------------------------

For small patches we recommend to do a single commit containing your
changes. For larger contributions you should try to group your work into
separate sub-tasks that you can commit one by one.

Before you create your patch you should make sure that your local
repository is up to date with the master repository. This is very
important especially if you work on your branch for a long time. Use the
following commands to pull the latest changes from the upstream
repository and rebase your branch against the current master.

[source,bash]
------------------------------
$ git checkout master
$ git pull --rebase
$ git checkout DELTASPIKE-XXX
$ git rebase master
------------------------------

Now you are ready to create your patch:

[source,bash]
--------------------------------------------------------------
$ git checkout DELTASPIKE-XXX
$ git format-patch --stdout master > ../DELTASPIKE-XXX.patch 
--------------------------------------------------------------

Please attach the resulting patch file to the correspoding JIRA issue.

===Applying patches


If you are a committer and want to apply a patch you should do so in a
separate branch.

---------------------------------
$ git checkout -b DELTASPIKE-XXX
---------------------------------

Then apply the patch using `git-am` and rebase it against the master
branch.

------------------------------------
$ git am < ../DELTASPIKE-XXX.patch 
$ git rebase master
------------------------------------

After reviewing the changes and testing the code, the changes are ready
to be merged into the master branch:

-------------------------------
$ git checkout master
$ git merge DELTASPIKE-XXX
$ git branch -d DELTASPIKE-XXX
-------------------------------


== Discussion workflow (optional)


All discussions which lead to a decision take place on the mailing list.
Sometimes it's required to show-case an idea especially if the solution is
more than a few lines. As shown above it makes sense to use local branches
for developing new parts. Git allows to push such local branches to a
public repository. So it's easier to share it with the community for
discussing it. The following listings show an example in combination
with GitHub - for sure it works with any hosting platform like
BitBucket, Google-Code,... The only important part here is that such
branches _NEVER_ get pushed to the main Apache repository to keep the
commit history as clean as possible.

*Initial setup*

[source,bash]
----------------------------------------------------------------------------------
$ git clone https://git-wip-us.apache.org/repos/asf/deltaspike.git ./
$ git remote add discuss https://[username]@github.com/[username]/[repo-name].git
$ git push -u discuss master
----------------------------------------------------------------------------------

*Branches for discussions*

[source,bash]
--------------------------------------------------
$ git checkout -b DELTASPIKE-XXX
//1-n commits
$ git push discuss DELTASPIKE-XXX
//share the link to the branch for the discussions
--------------------------------------------------

_If the community agrees on the suggested change, the implementation
will be applied to the origin master. A committer has to follow the
steps described above for the basic workflow to keep the commit history
simple, clean and straight. A contributor has to follow the steps
described above for creating a patch._

*Delete the branch again*

----------------------------------
$ git push discuss :DELTASPIKE-XXX
$ git branch -d DELTASPIKE-XXX
----------------------------------