Merge branch 'TOMEE-2345' of github.com:cchacin/tomee-site-generator
diff --git a/src/main/jbake/content/community/contributing/contribution-tips.adoc b/src/main/jbake/content/community/contributing/contribution-tips.adoc
index b6a8a69..59d6282 100755
--- a/src/main/jbake/content/community/contributing/contribution-tips.adoc
+++ b/src/main/jbake/content/community/contributing/contribution-tips.adoc
@@ -27,55 +27,7 @@
=== What is the process?
-```
-public void contributeToOpenSource() {
-
- boolean stillInterestedAndHavingFun = true;
- int taskSize = 1; // start small!
-
- contributing:
- while (stillInterestedAndHavingFun) {
-
- Task task = findSomethingInteresting(taskSize++);
-
- if (!task.hasJira()) {
- createJira(task);
- } else {
- requestToBeAssignedToJira(task.jiraId());
- }
-
- while (task.inProgress()) {
-
- chatOnListALittleGetCleverIdeas(task, new Ideas(task));
- hackALittle(task);
-
- if (task.tooHard() || task.notFun()) {
- // no big deal, try again with something else
- taskSize--;
- continue contributing;
- }
- }
-
- File patchFile = createSvnOrGitPatch(task);
- attachToJira(task.jiraId(), patchFile);
- askForReviewOnList(task.jiraId());
-
- while (!committed(patchFile)) {
-
- try {
- pokeAtSometingElse();
- helpOnUserList();
- dayDream();
- } catch (MoreThanAWeekException e) {
- // Assume it fell off the radar -- happens.
- // Evidence we need more committers.
- bumpThreadOnList(task);
- }
- }
- }
-
-}
-```
+Check and follow the link:workflow.html[workflow for contributing].
After a while when people feel comfortable with you as contributor, they vote you in as a committer and ... big surprise ... there's almost no change in the daily routine. You get access to svn and pretty much everything else stays the same. Instead of submitting patches, now you have to help review them and commit them. Instead of learning how to contribute to an open source project, now you have to learn how to help others get involved. And of course it doesn't happen all at once, you never stop learning these things and you never stop wishing you had more time.
diff --git a/src/main/jbake/content/community/contributing/jira-ticket.adoc b/src/main/jbake/content/community/contributing/jira-ticket.adoc
new file mode 100644
index 0000000..e7e3c43
--- /dev/null
+++ b/src/main/jbake/content/community/contributing/jira-ticket.adoc
@@ -0,0 +1,23 @@
+= JIRA ticket
+:jbake-date: 2018-12-10
+:jbake-type: page
+:jbake-status: published
+
+
+In order to keep track of all the tasks concerning TomEE there should be a ticket in the link:https://issues.apache.org/jira/browse/TOMEE[TomEE JIRA] for each work item. +
+Before you can create tickets, you have to link:https://issues.apache.org/jira/secure/Signup!default.jspa[sign up] for an account.
+
+=== No task without a ticket
+Before you start working on a task you should ensure that there is a ticket for your task. +
+Browse JIRA and use the search funktion to find out if there is already a ticket for what you want to pick up.
+If not, create a new one.
+
+=== Avoiding conflicts and wasted effort
+If a ticket already exists and is assign to someone you should not start working on this task. +
+If you want to help, contact the assigned person using the mailing list or write a comment in the JIRA ticket.
+
+=== Pick up a task
+To inform others that you are working on a task, the corresponding ticket in JIRA should be assigned to you. +
+If you don't have permission to assign tickets (there is no edit sign behind the Field "Assignee"), just ask on the developers mailing list.
+
+(link:workflow.html[back to Contribution workflow])
diff --git a/src/main/jbake/content/community/contributing/process-task.adoc b/src/main/jbake/content/community/contributing/process-task.adoc
new file mode 100644
index 0000000..3da95ca
--- /dev/null
+++ b/src/main/jbake/content/community/contributing/process-task.adoc
@@ -0,0 +1,27 @@
+= Process task
+:jbake-date: 2018-12-10
+:jbake-type: page
+:jbake-status: published
+
+
+=== Fork project repository
+You can work on the link:../sources.html[source code of TomEE] using github. If you don't have a github account, you can link:https://github.com/[sign up here]. +
+To create your own working area, go to the project link:https://github.com/apache/tomee[TomEE on github] and click on the link "Fork". A forked repository will be created for your account and you will be redirected to it.
+
+=== One branch for each ticket
+Although you can work on the master branch it is advisable to create a new branch for each ticket you start to work on - even if it's only one.
+Use the JIRA id and title as name of the branch.
+
+=== Get help
+If you need help or want to have feedback for your ideas write to the developes mailing list.
+
+=== Hands on
+Work on the code. Use local commit as often as you want. Use push (to your own forked repository) as often as you like. +
+Consider the link:contribution-tips.html[contribution tips]. +
+If a task is to hard to get it done: no problem. Just ask for help. +
+If you want to cancel working on a task, don't forget to unassign the JIRA ticket!
+
+=== Comments in JIRA
+Use comments for the JIRA ticket to document your work.
+
+(link:workflow.html[back to Contribution workflow])
diff --git a/src/main/jbake/content/community/contributing/submit-changes.adoc b/src/main/jbake/content/community/contributing/submit-changes.adoc
new file mode 100644
index 0000000..29beada
--- /dev/null
+++ b/src/main/jbake/content/community/contributing/submit-changes.adoc
@@ -0,0 +1,55 @@
+= Submit changes
+:jbake-date: 2018-12-10
+:jbake-type: page
+:jbake-status: published
+
+=== Ensure code compiles
+Actually no need to be mentioned ...
+
+=== Ensure tests passes
+On the build system for TomEE additional tests are run. If your changes cause them to fail, the build will not succeed.
+This can be avoided by running the tests before submitting the changes, the commands are:
+[source]
+----
+mvn -Pstyle checkstyle:check
+mvn -Pstyle pmd:check
+----
+These are relatively quick to run - about a minute or so.
+
+=== Smoke test
+Check at least if the server ist still starting with your changes ...
+
+=== Pull request
+If you're confident of your work, the next step is to push your changes into your repository on github.
+To get your changes back into the TomEE repository you have to create a PR (pull request): on github go to your repository and select the branch where you have worked on.
+Click on "New pull request" and then on "Create pull request".
+
+=== Request review
+The changes in your PR can only be merged by a committer who will do a review before merging.
+So ask on the developers mailing list for review of your PR.
+These emails for PRs should have a description of the work in the subject line.
+Here are some examples and why:
+
+==== Bad
+- This is an email about PR #451
+- See PR #451
+- Review PR #451
+- Help needed in PR #451 +
+
+With this style you'll get low participation on the thread as the subject is hidden. You yourself will curse these emails in six months or a year in the future when you're looking for that valuable thread you remember, but your search reveals 10 threads all with basically only a number as the subject. You'll either click and read all 10 PRs and email threads, or you'll more likely just give up. Worse, you may read all 10 and not find what you're looking for. Do your future self a favor and help him/her find the valuable discussions.
+
+==== Ok ...
+- Options pertaining to the configuration of Javamail - PR# 451
+- Fixing issues on failover of JMS messages - PR# 451
+- Documenting deployment of JCA Connectors - PR# 451 +
+
+These are ok, much better than just a number. Subjects are often truncated. The real "meat" is at the end of the sentence which makes it the first to go. Not a show-stopper, but can make your life hard when searching or scanning.
+
+==== Best!
+- Javamail configuration options - PR# 451
+- JMS Failover issues - PR# 451
+- JCA connector deployment - PR# 451 +
+
+Here we flip it. The real subject as at the beginning. The verbs and generic nouns like "options" come after. When you can pull it off, huge respect.
+
+(link:workflow.html[back to Contribution workflow])
diff --git a/src/main/jbake/content/community/contributing/workflow.adoc b/src/main/jbake/content/community/contributing/workflow.adoc
new file mode 100644
index 0000000..307a5a1
--- /dev/null
+++ b/src/main/jbake/content/community/contributing/workflow.adoc
@@ -0,0 +1,40 @@
+= Contribution Workflow
+:jbake-date: 2018-12-08
+:jbake-type: page
+:jbake-status: published
+
+:numbered:
+
+
+
+=== JIRA ticket
+- create ticket in JIRA, if not already existing
+- if ticket already assigned to someone else => talk
+- assign ticket to contributor, if not already assigned +
+ (link:jira-ticket.html[more details])
+
+
+
+=== Process Task
+- fork repository
+- create branch in own repository (name = JIRA ticket id)
+- discuss on mailing list
+- work on code
+- document work in JIRA ticket +
+ (link:process-task.html[more details])
+
+=== Submit Changes
+- ensure code compiles
+- ensure tests passes
+- create PR (pull request)
+- ask for review on mailing list +
+ (link:submit-changes.html[more details])
+
+=== Merge Changes (done by a committer)
+- review changes
+- merge code
+- change JIRA ticket status / close ticket +
+
+=== Cleanup
+- wait until PR is merged (ticket status change)
+- remove branch in own repository +
diff --git a/src/main/jbake/content/community/index.adoc b/src/main/jbake/content/community/index.adoc
index fd18c28..a222d62 100755
--- a/src/main/jbake/content/community/index.adoc
+++ b/src/main/jbake/content/community/index.adoc
@@ -7,6 +7,7 @@
=== Contribute
- link:contributing/contribution-tips.html[Contribution tips]
+- link:contributing/workflow.html[Contribution workflow]
- link:sources.html[Apache TomEE]
- link:contributing/website.html[This website]
- link:contributors.html[TomEE Wall Of Fame]
