This repository has been archived by the owner on May 14, 2018. It is now read-only.
forked from jboss-developer/jboss-eap-quickstarts
-
Notifications
You must be signed in to change notification settings - Fork 56
/
CONTRIBUTING.html
175 lines (147 loc) · 19 KB
/
CONTRIBUTING.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
<html><head><title>README</title><link href="https://raw.github.com/pmuir/github-flavored-markdown/gh-pages/shared/css/documentation.css" rel="stylesheet"></link><link href="https://raw.github.com/github/github-flavored-markdown/gh-pages/shared/css/pygments.css" rel="stylesheet"></link></head><body><h1 id="toc_0">Quickstarts Contributing Guide</h1>
<h2 id="toc_1">Purpose of the quickstarts</h2>
<ul>
<li><p>To demonstrate Java EE 6 technologies</p></li>
<li><p>To provide developers with working examples and instructions that are easy to follow .</p></li>
<li><p>To allow examples to be copied by developers and used as the basis for their own projects.</p></li>
</ul>
<h2 id="toc_2">Basic Steps</h2>
<p>To contribute to the quickstarts, fork the quickstart repository to your own Git, clone your fork, commit your work on topic branches, and make pull requests. </p>
<p>If you don't have the Git client (<code>git</code>), get it from: <a href="http://git-scm.com/">http://git-scm.com/</a></p>
<p>Here are the steps in detail:</p>
<ol>
<li><p><a href="https://github.com/jboss-jdf/jboss-as-quickstart/fork_select">Fork</a> the project. This creates a the project in your own Git.</p></li>
<li><p>Clone your fork. This creates a directory in your local file system.</p>
<div class="highlight"><pre><span class="n">git</span> <span class="n">clone</span> <span class="n">git</span><span class="p">@</span><span class="n">github</span><span class="p">.</span><span class="n">com</span><span class="p">:</span><span class="o"><</span><span class="n">your</span><span class="o">-</span><span class="n">username</span><span class="o">>/</span><span class="n">jboss</span><span class="o">-</span><span class="n">as</span><span class="o">-</span><span class="n">quickstart</span><span class="p">.</span><span class="n">git</span>
</pre>
</div></li>
<li><p>Add the remote <code>upstream</code> repository.</p>
<div class="highlight"><pre><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">git</span><span class="p">@</span><span class="n">github</span><span class="p">.</span><span class="n">com</span><span class="p">:</span><span class="n">jboss</span><span class="o">-</span><span class="n">jdf</span><span class="o">/</span><span class="n">jboss</span><span class="o">-</span><span class="n">as</span><span class="o">-</span><span class="n">quickstart</span><span class="p">.</span><span class="n">git</span>
</pre>
</div></li>
<li><p>Get the latest files from the <code>upstream</code> repository.</p>
<div class="highlight"><pre><span class="n">git</span> <span class="n">fetch</span> <span class="n">upstream</span>
</pre>
</div></li>
<li><p>Create a new topic branch to contain your features, changes, or fixes.</p>
<div class="highlight"><pre><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="o"><</span><span class="n">topic</span><span class="o">-</span><span class="n">branch</span><span class="o">-</span><span class="n">name</span><span class="o">></span> <span class="n">upstream</span><span class="o">/</span><span class="n">master</span>
</pre>
</div></li>
<li><p>Contribute new code or make changes to existing files. Make sure that you follow the General Guidelines below.</p></li>
<li><p>Commit your changes to your local topic branch. You must use <code>git add filename</code> for every file you create or change.</p>
<div class="highlight"><pre><span class="n">git</span> <span class="n">add</span> <span class="o"><</span><span class="n">changed</span><span class="o">-</span><span class="n">filename</span><span class="o">></span>
<span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> `<span class="n">Description</span> <span class="n">of</span> <span class="n">change</span><span class="p">...</span>`
</pre>
</div></li>
<li><p>Push your local topic branch to your github forked repository. This will create a branch on your Git fork repository with the same name as your local topic branch name.</p>
<div class="highlight"><pre><span class="n">git</span> <span class="n">push</span> <span class="n">origin</span> <span class="n">HEAD</span>
</pre>
</div></li>
<li><p>Browse to the <topic-branch-name> branch on your forked Git repository and <a href="http://help.github.com/send-pull-requests/">open a Pull Request</a>. Give it a clear title and description.</p></li>
</ol>
<h2 id="toc_3">General Guidelines</h2>
<ul>
<li><p>The sample project should be formatted using the JBoss AS profiles found at <a href="http://github.com/jboss/ide-config/tree/master/">http://github.com/jboss/ide-config/tree/master/</a></p>
<ul>
<li>Code should be well documented with good comments. Please add an author tag (@author) to credit yourself for writing the code.</li>
<li>You should use readable variable names to make it easy for users to read the code.</li>
</ul></li>
<li><p>The package must be <em>org.jboss.as.quickstarts</em></p></li>
<li><p>The quickstart project or folder name should match the quickstart name. Each sample project should have a unique name, allowing easy identification by users and developers.</p></li>
<li><p>If you create a quickstart that uses a database table, make sure the name you use for the table is unique across all quickstarts. </p></li>
<li><p>The project must follow the structure used by existing quickstarts such as <a href="https://github.com/jboss-jdf/jboss-as-quickstart/tree/master/numberguess">numberguess</a>. A good starting point would be to copy the <code>numberguess</code> project.</p></li>
<li><p>The sample project should be importable into JBoss Developer Studio/JBoss Tools and be deployable from there.</p></li>
<li><p>Maven POMs must be used. No other build system is allowed unless the purpose of the quickstart is to show another build system in use. If using Maven it should:</p>
<ul>
<li>Not inherit from another POM</li>
<li>Maven POMs must use the Java EE spec BOM/POM imports</li>
<li>The POMs must be commented, with a comment each item in the POM</li>
<li>Import the various BOMs, either directly from a project, or from <a href="http://www.jboss.org/jdf/stack/stacks/">JBoss BOMs</a>, to determine version numbers. You should aim to have no dependencies declared directly. If you do, work with the jdf team to get them added to a BOM.</li>
<li>Use the JBoss AS Maven Plugin to deploy the example</li>
</ul></li>
<li><p>The sample project must contain a <code>README.html</code> file using the <code>template/README.html</code> file as a guideline</p></li>
<li><p>Don't forget to update the <code>pom.xml</code> in the quickstart root directory. Add your quickstart to the 'modules' section.</p></li>
<li><p>The project must target Java 6</p>
<ul>
<li>CDI should be used as the programming model</li>
<li>Avoid using a web.xml if possible. Use faces-config.xml to activate JSF if needed.</li>
<li>Any tests should use Arquillian.</li>
</ul></li>
</ul>
<h2 id="toc_4">Kitchensink variants</h2>
<p>There are multiple quickstarts based on the kitchensink example. Each showcases different technologies and techniques including pure EE6, JSF, HTML5, and GWT. </p>
<p>If you wish to contribute a kitchensink variant is it important that you follow the look and feel of the original so that useful comparisons can be made. This does not mean that variants can not expand, and showcase additional functionality. Multiple variants already do that. These include mobile interfaces, push updates, and more.</p>
<p>Below are rules for the <em>look and feel</em> of the variants:</p>
<ul>
<li><p>Follow the primary layout, style, and graphics of the original.</p></li>
<li><p>Projects can have 3-4 lines directly under the AS/EAP banner in the middle section to describe what makes this variant different. </p>
<ul>
<li>How projects use that space is up to them, but options include plain text, bullet points, etc….<br/></li>
</ul></li>
<li><p>Projects can have their logo in the left side of the banner. </p>
<ul>
<li>The sidebar area can contain a section with links to the related projects, wiki, tutorials, etc…<br/>
<ul>
<li>This should be below any AS/EAP link areas.</li>
</ul></li>
</ul>
<p>If appropriate for the technology the application should expose RESTful endpoints following the example of the original kitchensink quickstart. This should also include the RESTful links in the member table.</p></li>
</ul>
<h2 id="toc_5">License Information and Contributor Agreement</h2>
<p>JBoss Developer Framework is licensed under the Apache License 2.0, as we believe it is one of the most permissive Open Source license. This allows developers to easily make use of the code samples in JBoss Developer Framework. </p>
<p>There is no need to sign a contributor agreement to contribute to JBoss Developer Framework. You just need to explicitly license any contribution under the AL 2.0. If you add any new files to JBoss Developer Framework, make sure to add the correct header.</p>
<h3 id="toc_6">Java</h3>
<div class="highlight"><pre> <span class="o">/*</span>
<span class="o">*</span> <span class="n">JBoss</span><span class="p">,</span> <span class="n">Home</span> <span class="n">of</span> <span class="n">Professional</span> <span class="n">Open</span> <span class="n">Source</span>
<span class="o">*</span> <span class="n">Copyright</span> <span class="o"><</span><span class="n">Year</span><span class="o">></span><span class="p">,</span> <span class="n">Red</span> <span class="n">Hat</span><span class="p">,</span> <span class="n">Inc</span><span class="p">.</span> <span class="n">and</span><span class="o">/</span><span class="n">or</span> <span class="n">its</span> <span class="n">affiliates</span><span class="p">,</span> <span class="n">and</span> <span class="n">individual</span>
<span class="o">*</span> <span class="n">contributors</span> <span class="n">by</span> <span class="n">the</span> <span class="p">@</span><span class="n">authors</span> <span class="n">tag</span><span class="p">.</span> <span class="n">See</span> <span class="n">the</span> <span class="n">copyright</span><span class="p">.</span><span class="n">txt</span> <span class="n">in</span> <span class="n">the</span>
<span class="o">*</span> <span class="n">distribution</span> <span class="k">for</span> <span class="n">a</span> <span class="n">full</span> <span class="n">listing</span> <span class="n">of</span> <span class="n">individual</span> <span class="n">contributors</span><span class="p">.</span>
<span class="o">*</span>
<span class="o">*</span> <span class="n">Licensed</span> <span class="n">under</span> <span class="n">the</span> <span class="n">Apache</span> <span class="n">License</span><span class="p">,</span> <span class="n">Version</span> 2<span class="p">.</span>0 <span class="p">(</span><span class="n">the</span> "<span class="n">License</span>"<span class="p">);</span>
<span class="o">*</span> <span class="n">you</span> <span class="n">may</span> <span class="n">not</span> <span class="n">use</span> <span class="n">this</span> <span class="n">file</span> <span class="n">except</span> <span class="n">in</span> <span class="n">compliance</span> <span class="n">with</span> <span class="n">the</span> <span class="n">License</span><span class="p">.</span>
<span class="o">*</span> <span class="n">You</span> <span class="n">may</span> <span class="n">obtain</span> <span class="n">a</span> <span class="n">copy</span> <span class="n">of</span> <span class="n">the</span> <span class="n">License</span> <span class="n">at</span>
<span class="o">*</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">licenses</span><span class="o">/</span><span class="n">LICENSE</span><span class="o">-</span>2<span class="p">.</span>0
<span class="o">*</span> <span class="n">Unless</span> <span class="n">required</span> <span class="n">by</span> <span class="n">applicable</span> <span class="n">law</span> <span class="n">or</span> <span class="n">agreed</span> <span class="n">to</span> <span class="n">in</span> <span class="n">writing</span><span class="p">,</span> <span class="n">software</span>
<span class="o">*</span> <span class="n">distributed</span> <span class="n">under</span> <span class="n">the</span> <span class="n">License</span> <span class="n">is</span> <span class="n">distributed</span> <span class="n">on</span> <span class="n">an</span> "<span class="n">AS</span> <span class="n">IS</span>" <span class="n">BASIS</span><span class="p">,</span>
<span class="o">*</span> <span class="n">WITHOUT</span> <span class="n">WARRANTIES</span> <span class="n">OR</span> <span class="n">CONDITIONS</span> <span class="n">OF</span> <span class="n">ANY</span> <span class="n">KIND</span><span class="p">,</span> <span class="n">either</span> <span class="n">express</span> <span class="n">or</span> <span class="n">implied</span><span class="p">.</span>
<span class="o">*</span> <span class="n">See</span> <span class="n">the</span> <span class="n">License</span> <span class="k">for</span> <span class="n">the</span> <span class="n">specific</span> <span class="n">language</span> <span class="n">governing</span> <span class="n">permissions</span> <span class="n">and</span>
<span class="o">*</span> <span class="n">limitations</span> <span class="n">under</span> <span class="n">the</span> <span class="n">License</span><span class="p">.</span>
<span class="o">*/</span>
</pre>
</div>
<h3 id="toc_7">XML</h3>
<div class="highlight"><pre> <span class="o"><</span>!<span class="o">--</span>
<span class="n">JBoss</span><span class="p">,</span> <span class="n">Home</span> <span class="n">of</span> <span class="n">Professional</span> <span class="n">Open</span> <span class="n">Source</span>
<span class="n">Copyright</span> <span class="o"><</span><span class="n">Year</span><span class="o">></span><span class="p">,</span> <span class="n">Red</span> <span class="n">Hat</span><span class="p">,</span> <span class="n">Inc</span><span class="p">.</span> <span class="n">and</span><span class="o">/</span><span class="n">or</span> <span class="n">its</span> <span class="n">affiliates</span><span class="p">,</span> <span class="n">and</span> <span class="n">individual</span>
<span class="n">contributors</span> <span class="n">by</span> <span class="n">the</span> <span class="p">@</span><span class="n">authors</span> <span class="n">tag</span><span class="p">.</span> <span class="n">See</span> <span class="n">the</span> <span class="n">copyright</span><span class="p">.</span><span class="n">txt</span> <span class="n">in</span> <span class="n">the</span>
<span class="n">distribution</span> <span class="k">for</span> <span class="n">a</span> <span class="n">full</span> <span class="n">listing</span> <span class="n">of</span> <span class="n">individual</span> <span class="n">contributors</span><span class="p">.</span>
<span class="n">Licensed</span> <span class="n">under</span> <span class="n">the</span> <span class="n">Apache</span> <span class="n">License</span><span class="p">,</span> <span class="n">Version</span> 2<span class="p">.</span>0 <span class="p">(</span><span class="n">the</span> "<span class="n">License</span>"<span class="p">);</span>
<span class="n">you</span> <span class="n">may</span> <span class="n">not</span> <span class="n">use</span> <span class="n">this</span> <span class="n">file</span> <span class="n">except</span> <span class="n">in</span> <span class="n">compliance</span> <span class="n">with</span> <span class="n">the</span> <span class="n">License</span><span class="p">.</span>
<span class="n">You</span> <span class="n">may</span> <span class="n">obtain</span> <span class="n">a</span> <span class="n">copy</span> <span class="n">of</span> <span class="n">the</span> <span class="n">License</span> <span class="n">at</span>
<span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="p">.</span><span class="n">apache</span><span class="p">.</span><span class="n">org</span><span class="o">/</span><span class="n">licenses</span><span class="o">/</span><span class="n">LICENSE</span><span class="o">-</span>2<span class="p">.</span>0
<span class="n">Unless</span> <span class="n">required</span> <span class="n">by</span> <span class="n">applicable</span> <span class="n">law</span> <span class="n">or</span> <span class="n">agreed</span> <span class="n">to</span> <span class="n">in</span> <span class="n">writing</span><span class="p">,</span> <span class="n">software</span>
<span class="n">distributed</span> <span class="n">under</span> <span class="n">the</span> <span class="n">License</span> <span class="n">is</span> <span class="n">distributed</span> <span class="n">on</span> <span class="n">an</span> "<span class="n">AS</span> <span class="n">IS</span>" <span class="n">BASIS</span><span class="p">,</span>
<span class="n">WITHOUT</span> <span class="n">WARRANTIES</span> <span class="n">OR</span> <span class="n">CONDITIONS</span> <span class="n">OF</span> <span class="n">ANY</span> <span class="n">KIND</span><span class="p">,</span> <span class="n">either</span> <span class="n">express</span> <span class="n">or</span> <span class="n">implied</span><span class="p">.</span>
<span class="n">See</span> <span class="n">the</span> <span class="n">License</span> <span class="k">for</span> <span class="n">the</span> <span class="n">specific</span> <span class="n">language</span> <span class="n">governing</span> <span class="n">permissions</span> <span class="n">and</span>
<span class="n">limitations</span> <span class="n">under</span> <span class="n">the</span> <span class="n">License</span><span class="p">.</span>
<span class="o">--></span>
</pre>
</div>
<h3 id="toc_8">Properties files</h3>
<div class="highlight"><pre> <span class="c"># JBoss, Home of Professional Open Source</span>
<span class="c"># Copyright 2012, Red Hat, Inc. and/or its affiliates, and individual</span>
<span class="c"># contributors by the @authors tag. See the copyright.txt in the </span>
<span class="c"># distribution for a full listing of individual contributors.</span>
<span class="c">#</span>
<span class="c"># Licensed under the Apache License, Version 2.0 (the "License");</span>
<span class="c"># you may not use this file except in compliance with the License.</span>
<span class="c"># You may obtain a copy of the License at</span>
<span class="c"># http://www.apache.org/licenses/LICENSE-2.0</span>
<span class="c"># Unless required by applicable law or agreed to in writing, software</span>
<span class="c"># distributed under the License is distributed on an "AS IS" BASIS, </span>
<span class="c"># WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.</span>
<span class="c"># See the License for the specific language governing permissions and</span>
<span class="c"># limitations under the License.</span>
</pre>
</div>
</body></html>