You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<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>
22
+
<p>If you don't have the Git client (<code>git</code>), get it from: <ahref="http://git-scm.com/">http://git-scm.com/</a></p>
23
+
<p>Here are the steps in detail:</p>
24
+
<ol>
25
+
<li>
26
+
<p><ahref="https://github.com/wildfly/quickstart/fork_select">Fork</a> the project. This creates a the project in your own Git with the default remote name 'origin'.</p>
27
+
</li>
28
+
<li>
29
+
<p>Clone your fork. This creates and populates a directory in your local file system.</p>
<p>Get the latest files from the <code>upstream</code> repository.</p>
40
+
<pre><code>git fetch upstream
41
+
</code></pre>
42
+
</li>
43
+
<li>
44
+
<p>Create a new topic branch to contain your features, changes, or fixes using the <code>git checkout -b <topic-branch-name> upstream/master</code> command. For example:</p>
<p>Contribute new code or make changes to existing files. Make sure that you follow the <em>General Guidelines</em> below.</p>
50
+
</li>
51
+
<li>
52
+
<p>To verify if your code followed the General Guidelines you can run <ahref="http://www.jboss.org/jdf/quickstarts/qstools/">QS Tools</a> on your project.</p>
53
+
</li>
54
+
</ol>
55
+
<ul>
56
+
<li>To run QS Tools, go to your quickstart project root and execute:
<p>This will generate a report on <code>QUICKSTART_HOME/target/site/qschecker.html</code>. Review the report to determine if your quickstart project violates any item in the <em>General Guidelines</em>.</p>
62
+
<ol>
63
+
<li>Use the <code>git add</code> command to add new or changed file contents to the staging area.</li>
64
+
</ol>
65
+
<ul>
66
+
<li>If you create a new quickstart, you can add files using the subfolder and file names. The following is an example of new quickstart folders and files you may want to stage:
67
+
<pre><code> git add src/
68
+
git add pom.xml
69
+
git add README.md
70
+
</code></pre>
71
+
</li>
72
+
</ul>
73
+
<p><em>Note: It is probably best not to add the entire quickstart root folder because you may unintentionally add classes or other target files that should not be in source control.</em><br/>
74
+
* If you only modified a few files, use <code>git add <filename></code> for every file you create or change. For example:</p>
75
+
<pre><code> git add README.md
76
+
</code></pre>
77
+
<ol>
78
+
<li>
79
+
<p>Use the git status command to view the status of the files in the directory and in the staging area and ensure that all modified files are properly staged:</p>
80
+
<pre><code>git status
81
+
</code></pre>
82
+
</li>
83
+
<li>
84
+
<p>Commit your changes to your local topic branch.</p>
85
+
<pre><code>git commit -m 'Description of change...'
86
+
</code></pre>
87
+
</li>
88
+
<li>
89
+
<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>
90
+
<pre><code>git push origin HEAD
91
+
</code></pre>
92
+
</li>
93
+
</ol>
94
+
<p><em>Note: The above command assumes your remote repository is named 'origin'. You can verify your forked remote repository name using the command <code>git remote -v</code></em>. 12. Browse to the <topic-branch-name> branch on your forked Git repository and <ahref="http://help.github.com/send-pull-requests/">open a Pull Request</a>. Give it a clear title and description.</p>
<p>The sample project should be formatted using the WildFly profiles found at <ahref="http://github.com/jboss/ide-config/tree/master/">http://github.com/jboss/ide-config/tree/master/</a></p>
99
+
</li>
100
+
<li>
101
+
<p>Code should be well documented with good comments. Please add an author tag (@author) to credit yourself for writing the code.</p>
102
+
</li>
103
+
<li>You should use readable variable names to make it easy for users to read the code.</li>
104
+
<li>
105
+
<p>The package must be <em>org.wildfly.quickstarts</em></p>
106
+
</li>
107
+
<li>
108
+
<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>
109
+
</li>
110
+
<li>
111
+
<p>The quickstart project <code><artifactId></code> in the <code>pom.xml</code> file must be prefixed by <code>wildfly-</code>. For example, the <code><artifactId></code> for a <code>is-f-fast</code> quickstart is <code>wildfly-is-f-fast</code>.</p>
112
+
</li>
113
+
<li>
114
+
<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>
115
+
</li>
116
+
<li>
117
+
<p>The project must follow the structure used by existing quickstarts such as <ahref="https://github.com/wildfly/quickstart/tree/master/numberguess">numberguess</a>. A good starting point would be to copy the <code>numberguess</code> project.</p>
118
+
</li>
119
+
<li>
120
+
<p>The sample project should be importable into JBoss Developer Studio/JBoss Tools and be deployable from there.</p>
121
+
</li>
122
+
<li>
123
+
<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>
124
+
</li>
125
+
<li>
126
+
<p>Not inherit from another POM</p>
127
+
</li>
128
+
<li>Maven POMs must use the Java EE spec BOM/POM imports</li>
129
+
<li>The POMs must be commented, with a comment each item in the POM</li>
130
+
<li>Import the various BOMs, either directly from a project, or from <ahref="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>
131
+
<li>Use the WildFly Maven Plugin to deploy the example</li>
132
+
<li>
133
+
<p>The sample project must contain a <code>README.md</code> file using the <code>template/README.md</code> file as a guideline</p>
134
+
</li>
135
+
<li>
136
+
<p>Don't forget to update the <code>pom.xml</code> in the quickstart root directory. Add your quickstart to the 'modules' section.</p>
137
+
</li>
138
+
<li>
139
+
<p>The project must target Java 6</p>
140
+
</li>
141
+
<li>
142
+
<p>CDI should be used as the programming model</p>
143
+
</li>
144
+
<li>Avoid using a web.xml if possible. Use faces-config.xml to activate JSF if needed.</li>
<p>There are multiple quickstarts based on the kitchensink example. Each showcases different technologies and techniques including pure EE7, JSF, HTML5, and GWT.</p>
149
+
<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>
150
+
<p>Below are rules for the <em>look and feel</em> of the variants:</p>
151
+
<ul>
152
+
<li>
153
+
<p>Follow the primary layout, style, and graphics of the original.</p>
154
+
</li>
155
+
<li>
156
+
<p>Projects can have 3-4 lines directly under the WildFly banner in the middle section to describe what makes this variant different.</p>
157
+
<ul>
158
+
<li>How projects use that space is up to them, but options include plain text, bullet points, etc....</li>
159
+
</ul>
160
+
</li>
161
+
<li>
162
+
<p>Projects can have their logo in the left side of the banner.</p>
163
+
<ul>
164
+
<li>The sidebar area can contain a section with links to the related projects, wiki, tutorials, etc...</li>
165
+
<li>This should be below any WildFly link areas.</li>
166
+
</ul>
167
+
<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>
168
+
</li>
169
+
</ul>
170
+
<h2><ahref="#setup-your-environment" id="setup-your-environment">Setup your environment</a></h2>
171
+
<p>The quickstart README.md files are converted to HTML using markdown. We recommend using redcarpet, as that is what github uses, but you can use any markdown tool really.</p>
172
+
<p>There are two scripts, <code>dist/github-flaoured-markdown.rb</code>, that will convert an individual file, and <code>dist/release-utils.sh -m</code>, that will convert all the files.</p>
173
+
<p>To setup the environment you need to follow these steps.</p>
174
+
<ol>
175
+
<li>
176
+
<p>Install Ruby <em>1.9.X</em></p>
177
+
<p>For RHEL you can use this <ahref="https://github.com/lnxchk/ruby-1.9.3-rpm">spec</a></p>
178
+
<p>In general, you're better off not relying on your OSs ruby install, they are often quite broken.</p>
<p>You'll need python eggs installed, which often isn't available on OS installs of python. Google to find out how to install it</p>
188
+
</li>
189
+
<li>
190
+
<p>Install pygments</p>
191
+
<pre><code> sudo easy_install pygments
192
+
</code></pre>
193
+
</li>
194
+
</ol>
195
+
<h2><ahref="#license-information-and-contributor-agreement" id="license-information-and-contributor-agreement">License Information and Contributor Agreement</a></h2>
196
+
<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>
197
+
<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>
198
+
<h3><ahref="#java-javascript-and-css-files" id="java-javascript-and-css-files">Java, Javascript and CSS files</a></h3>
199
+
<pre><code> /**
200
+
* JBoss, Home of Professional Open Source
201
+
* Copyright 2015, Red Hat, Inc. and/or its affiliates, and individual
202
+
* contributors by the @authors tag. See the copyright.txt in the
203
+
* distribution for a full listing of individual contributors.
204
+
*
205
+
* Licensed under the Apache License, Version 2.0 (the "License");
206
+
* you may not use this file except in compliance with the License.
207
+
* You may obtain a copy of the License at
208
+
* http://www.apache.org/licenses/LICENSE-2.0
209
+
* Unless required by applicable law or agreed to in writing, software
210
+
* distributed under the License is distributed on an "AS IS" BASIS,
211
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
212
+
* See the License for the specific language governing permissions and
213
+
* limitations under the License.
214
+
*/
215
+
</code></pre>
216
+
<h3><ahref="#html-xml-xsd-and-xhtml-files" id="html-xml-xsd-and-xhtml-files">HTML, XML, XSD and XHTML files</a></h3>
217
+
<pre><code> <!--
218
+
JBoss, Home of Professional Open Source
219
+
Copyright 2015, Red Hat, Inc. and/or its affiliates, and individual
220
+
contributors by the @authors tag. See the copyright.txt in the
221
+
distribution for a full listing of individual contributors.
222
+
223
+
Licensed under the Apache License, Version 2.0 (the "License");
224
+
you may not use this file except in compliance with the License.
225
+
You may obtain a copy of the License at
226
+
http://www.apache.org/licenses/LICENSE-2.0
227
+
Unless required by applicable law or agreed to in writing, software
228
+
distributed under the License is distributed on an "AS IS" BASIS,
229
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
230
+
See the License for the specific language governing permissions and
231
+
limitations under the License.
232
+
-->
233
+
</code></pre>
234
+
<h3><ahref="#properties-files-and-bash-scripts" id="properties-files-and-bash-scripts">Properties files and Bash Scripts</a></h3>
235
+
<pre><code> # JBoss, Home of Professional Open Source
236
+
# Copyright 2015, Red Hat, Inc. and/or its affiliates, and individual
237
+
# contributors by the @authors tag. See the copyright.txt in the
238
+
# distribution for a full listing of individual contributors.
239
+
#
240
+
# Licensed under the Apache License, Version 2.0 (the "License");
241
+
# you may not use this file except in compliance with the License.
242
+
# You may obtain a copy of the License at
243
+
# http://www.apache.org/licenses/LICENSE-2.0
244
+
# Unless required by applicable law or agreed to in writing, software
245
+
# distributed under the License is distributed on an "AS IS" BASIS,
246
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
247
+
# See the License for the specific language governing permissions and
0 commit comments