<commit_before>= Groovy Contributions
 
++++
<link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.11.0/themes/blitzer/jquery-ui.css">
++++

<<<

== Help !

A key area we've been working on for a while is our new [blue]#Groovy# documentation. <NAME> has detailed how you can help us author some sections of the documentation. http://blog.cacoethes.co.uk/groovyandgrails/contributing-to-the-groovy-documentation[Read his post here]. 

Like Peter, you can dedicate a bit of your time on a topic of your choice, to further deepen your understanding of a particular area of [blue]#Groovy# and share your knowledge with your peers.

We really look forward to your contributions!

.Your Contributions
****
The [blue]#Groovy# core team is a very small team, compared to the huge team a company like Oracle puts behind Java and the JVM, or Microsoft behind its languages and the .Net platform. So all contributions, in any form, do count, and are important to the success and evolution of the [blue]#Groovy# language.
****

<<<

== Contributions Walk-Thru 

.Prerequisites
 - [*] Working internet connection
 - [ ] Familiarity with computer directory organization, folders, sub-directories and structures of hierarchies
 - [ ] Have a GitHub Account and familiarity with concepts about code repositories - also called *repo-s*
 - [ ] Knowledge of computer terminal command line
 - [ ] Installed *GIT* tool
 - [ ] Plain text editor like TEXTEDIT, NOTEPAD, gedit, Leafpad; - a tool that does *NOT* include markup like bold,italics, etc. and saves file in the *UTF-8* character set
 - [ ] Be familiar with http://asciidoctor.org/docs/user-manual/[Asciidoctor markup] and the  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[syntax reference guide] ( more notes are listed below ).
 - [ ] Optionally - have the http://asciidoctor.org/docs/install-toolchain/[*asciidoctor* toolchain] installed on your local system
 - [ ] Be familiar with unit testing of individual programs; it may be necessary to write some new test cases for groovy modules. ( _Optional_ )
 - [ ] Enthusiasm and nice writing style  

'''

IMPORTANT: It's *NOT* necessary to have [blue]#Groovy# installed on your local system to be able to write documentation.

'''

=== Join Us !

Please join any of our mailing lists at http://groovy-lang.org/mailing-lists.html[http://groovy-lang.org/mailing-lists.html]. 

Whether you are a user, developer, or enthusiast, we have a choice of mailing lists you may find appealing. Ask and get answers for questions about the [blue]#Groovy# eco-system.

You can find live icon:twitter[] https://twitter.com/hashtag/groovylang[#groovylang] feeds for up-to-the-minute news.

'''


=== Where is Groovy ?

Open source developers often need somewhere to keep all their assets. These assets are typically stored in a repository somewhere on the internet. icon:github[link="https://github.com/"] https://github.com/[*GitHub*] is one such storage facility. At *[blue]#Groovy#*, we keep https://github.com/groovy/groovy-core[our _source code_ here]. 

Visit our *[blue]#Groovy#* information portal at image:assets/img/groovy.png[Groovy Website, 60, 30, link="http://groovy-lang.org/"] 

We build *[blue]#Groovy#* continuously at image:assets/img/teamcity.png[TeamCity, 73, 20, link="http://ci.groovy-lang.org/"]. Log in as a guest.


=== How Do I Contribute ?

There are two paths to contribute : 

For small things, you can change the relevant document on-line, within the *GitHub* system. For spelling or punctuation typos, broken language, etc, you can edit the document live from within Github. We mention this approach for small contributions that don't require us to run the tests / create or update new tests. link:#_quick_fixes[Follow this trail.]

For larger contributions, it's more likely you'll need to copy [blue]#Groovy# into your own work environment, then link:#_take_the_long_way_home[Take The Long Way Home.]

== Quick Fixes To Groovy

Sometimes, you may spot a tiny flaw in our otherwise perfect product. It's bugging you, so you want to fix it quickly without all the trouble of porting [blue]#Groovy# to your own system. Can it be done ?

[red yellow-background big]*Sure icon:exclamation[]*

Let's say you need to fix the [blue]#Groovy# README.adoc file in https://github.com/groovy/groovy-core[https://github.com/groovy/groovy-core] - our core location.

'''

IMPORTANT: Only use this way to fix small stuff like spelling bits. Otherwise your fix may avoid our indepth testing process [red yellow-background big]*:-(*

'''

Click the core location address to get here :

.Groovy Core Page
image::assets/img/example15.png[Details, align="center"] 

Your view should look like this, except it will say +groovy / groovy-core+ ( this view was from another example and has the wrong location name ). Confirm you are viewing +groovy / groovy-core+ then click the name of the resource to edit, in this case *README.adoc*. The following view opens.

'''

.README.adoc View
image::assets/img/example16.png[Details, align="center", link="https://github.com/groovy/groovy-core/blob/master/README.adoc"] 

This view is the current content of the *README* file. You can see ( but not edit ) the raw text by clicking the +RAW+ button. But for this example, you want to change some text. The red arrow points to the editor *PENCIL*. Click that to open an editable version of this page. See below.


'''

.Groovy-core/README.adoc page
image::assets/img/example17.png[Details, align="center", link="https://github.com/groovy/groovy-core/blob/master/README.adoc"] 

Confirm you're on the correct page ( blue square ). Then on line 80, after the words _Continuous Integration_ add the word _Server_

'''

Then add more details like this :

.Ready To Roll
image::assets/img/example18.png[Details, align="center"] 

In the box marked *Commit changes* add a short descriptive title and add more detail below. Then click [white green-background big]*Commit changes* button to seal the deal. Easy-peasy icon:exclamation[]  icon:smile[]

<<<

== Take The Long Way Home

This way needs more work on your part though it it is more rewarding too.

First we look at the home of [blue]#Groovy# . Then we review the structure and important items. After that we pick up the story at link:#_getting_started[Getting Started.]

=== Notes About GitHub

At *[blue]#Groovy#*, we keep https://github.com/groovy/groovy-core[our _source code_ here].

==== GitHub Information

++++
<div id="accordion2">
  <h3>Typical Workflow Steps</h3>
  <div>
<ul>
<li>join GitHub
<li>sign in to your GitHub account
<li>locate the groovy code base
<li>make a copy ( FORK ) of it into your own online GitHub account
 <li>make a local copy ( CLONE ) from your own online GitHub account
 <li>create a new feature branch
 <li>switch to your new feature branch
 <li>build/amend the documents
 <li>provide screen images if needed
 <li>provide test cases to match your documentation
 <li>build and test everything
 <li>commit your changes
 <li>switch to your master branch
 <li>merge your branch full of changes into the master branch
 <li>send ( PUSH ) your changes back to your own online account
 <li>ask the groovy admins to include ( PULL ) your changes in the groovy code base
</ul>
  </div>

  <h3>Git Clients</h3>
  <div>
<ul>
<li><a href="http://git-scm.com/downloads/guis" target="_blank">Git Client GUIs for All Platforms</a></li>
<li><a href="http://docs.oseems.com/general/operatingsystem/ubuntu/install-git-client" target="_blank">Git Client for Ubuntu</a></li>
<li><a href="http://msysgit.github.io/" target="_blank">Git Client for Windows</a></li>
</ul>
</div>

  <h3>Git References</h3>
  <div>
<ul>
<li><a href="https://help.github.com/articles/set-up-git" target="_blank">Setup Git</a></li>
<li><a href="https://help.github.com/articles/signing-up-for-a-new-github-account" target="_blank">Sign-up for a new Github account</a></li>
<li><a href="https://help.github.com/articles/fork-a-repo" target="_blank">Fork a repo</a></li>
<li><a href="http://gitref.org/branching/" target="_blank">Git Branching and Merging</a></li>
<li><a href="https://gun.io/blog/how-to-github-fork-branch-and-pull-request/" target="_blank">Git Rebase</a></li>
<li><a href="http://www.markjberger.com/git-tips-for-beginners/" target="_blank">Tips for beginners</a></li>
<li><a href="http://blog.guy.ht/2010/12/using-branches-to-manage-documentation-on-github/" target="_blank">Manage With Branches</a></li>
</ul>
</div>


</div>
++++

+++<br />+++

'''


=== Groovy Directory Structure

From here on, we've assumed you have logged into your own *GitHub* account. 

==== Visit Groovy Core Repository on GitHub

Open a web browser, then use address https://github.com/groovy/groovy-core[https://github.com/groovy/groovy-core] to review the [blue]#Groovy# code base. It looks like this :

.Groovy Core on *Github* icon:github[link="https://github.com/groovy/groovy-core", window="_blank"]
image::assets/img/github4.png[Groovy Core Repository on GitHub, 495, 436, link="https://github.com/groovy/groovy-core",align="center"] 

There are a number of folders within the [blue]#Groovy# code base. The most important folders are */src* and */subprojects* as these folders hold the base code and scripts for [blue]#Groovy#.

==== The +/src+ Folder

The core of [blue]#Groovy# lives within this folder. Here is where we find a variety of artifacts, scripts, tests, resources, images, etc. 

.Groovy Core Source Folder on *Github* icon:github[link="https://github.com/groovy/groovy-core/tree/master/src", window="_blank"]
image::assets/img/github1.png[Groovy Core Source, 497, 313, link="https://github.com/groovy/groovy-core/tree/master/src",align="center"] 


==== The +/subprojects+ Folder

[blue]#Groovy# has many additional features that are not part of the core system. Source code for these added features can be found in the *subprojects* folder. It looks something like this :

.Groovy Core Sub-Projects Source Folder on *Github*  icon:github[link="https://github.com/groovy/groovy-core/tree/master/subprojects", window="_blank"]
image::assets/img/github2.png[Groovy Core Source, 499, 397, link="https://github.com/groovy/groovy-core/tree/master/subprojects",align="center"] 

==== The Documentation Folder

Within each */src* and */subproject/src* is a */spec* documents folder that exists, or will soon be created. 

.Groovy Document Specifications Folder on *Github*  icon:github[link="https://github.com/groovy/groovy-core/tree/master/src/spec", window="_blank"]
image::assets/img/github3.png[Groovy Documents Source, 500, 185, link="https://github.com/groovy/groovy-core/tree/master/src/spec",align="center"] 

The two most useful folders here are */doc* and */test*. These two folders hold our documents and test cases.

===== Documents

All of our documents are written as typical text files encoded as *UTF-8* characters. The text is styled in the markup syntax known as http://asciidoctor.org/docs/user-manual/[*asciidoc*] or http://asciidoctor.org/docs/user-manual/[*asciidoctor*] ( the more recent version ). These text files have a filename suffix designation of *.adoc*.

.Groovy Documentation Folder on *Github*
image::assets/img/github5.png[Groovy Documents Folder, 501, 170, link="https://github.com/groovy/groovy-core/tree/master/src/spec/doc",align="center"] 

===== Test Cases

To prove that [blue]#Groovy# modules work as expected, we often construct test cases that exercise code logic. These test cases are actually [blue]#Groovy# scripts that reside in the */test* folder.

.Groovy Core Test Folder on *Github* icon:github[link="https://github.com/groovy/groovy-core/tree/master/src/spec/test", window="_blank"]
image::assets/img/github6.png[Groovy Testcase Folder, 505, 303, link="https://github.com/groovy/groovy-core/tree/master/src/spec/test",align="center"] 

If you would like to know more about writing effective test cases, please http://groovy-lang.org/testing.html[review this link].
 
 
==== Wrap Up

Ok, that's a quick review of our [blue]#Groovy# code base, the directory/folder structure and important bits. It _should_ give you a starting point  to explore [blue]#Groovy# icon:thumbs-up-alt[]

'''

<<<

== Getting Started
 
Let's assume you've logged into your *GitHub* account.

.*GitHub* Home Panel
image::assets/img/githubhomepanel.png[Github Home Panel, align="center"] 
 
This is the typical panel you use to work with *GitHub*. It has a variety of things you can do. You'll need to search for the [blue]#Groovy# repository, so look at the top of this panel. See that field named +Search or type a command+ ? Let's use  that to icon:search[].

'''

=== Make [blue]#Groovy# Your Own 

.Search icon:search[] on *GitHub* for Groovy-Core
image::assets/img/githubsearch.png[Github Search Feature,align="center"] 

Ok, let's look for the *groovy-core* repository. In the field named +Search or type a command+ enter *groovy-core* then click +Search+. You should see a repository named *groovy/groovy-core* so click that to visit the home of [blue]#Groovy#.

''' 

.Fork Groovy Core on *GitHub*
image::assets/img/githubfork.png[Fork The Code, 541, 156, link="https://github.com/groovy/groovy-core",align="center"] 

So you can work on your own version of [blue]#Groovy#, you'll need to make a copy of it. This copy is placed in your own *GitHub* account under your credentials. This task of making a copy is known as *Fork* -ing.

Check you're logged into your own *GitHub* account before you start to search.

Fork the https://github.com/groovy/groovy-core[groovy/groovy-core] repository on *GitHub* to your own *GitHub* account. Click the +Fork+ button while on the *groovy/groovy-core* panel. When you look at your own *GitHub* home page, you'll see the list of your forked repos and any new repos you make.

.Fork Groovy Core on *GitHub*
image::assets/img/repolist.png[List of Repos, link="https://github.com/groovy/groovy-core",align="center"] 

You now have your own version of [blue]#Groovy# in your *GitHub* account on the remote server. Next, you'll want to bring a copy of it onto your local system. It's easier to work with documents and test cases that way.

'''

TIP: See this https://gun.io/blog/how-to-github-fork-branch-and-pull-request/[gun.io] tutorial covering fork, branch, pull tactics.

'''

=== Terminally Yours

[source,role="console",options="nowrap"]
.Commands
----
Open a terminal/command prompt
Make a folder to hold your copy of Groovy; for now, create a folder named groovy-core
Change directories ( cd ) into your groovy-core version of the directory.
----

=== Copy [blue]#Groovy#

Clone/copy your forked repository from your own *GitHub* account to your local system, then check which version of the *Java* runtime environment you have. 

[source,role="console",options="nowrap"]
.Command - ( replace xxxxx with your *GitHub* nickname )
----
git clone https://github.com/xxxxxx/groovy-core.git
cd groovy-core
java -version
----

.Terminal Console Afterward
image::assets/img/console1.png[List of Commands, align="center"] 

If your java version is earlier than 1.6 you might not be able to do much testing. If it's recent then change directories into the *groovy-core* folder. 

'''

=== Check Your Installation

To make sure you can build and test your [blue]#Groovy# version, try to build just the [blue]#Groovy# document suite. 

.Run one of these commands depending on your operating system:
 * +bash ./gradlew asciidocAll+ on Linux/Ubuntu 
 * +gradlew asciidocAll+ on Windows
 * +./gradlew asciidocAll+ for Apple

Your sample log might look like this :

++++
<div id="accordion">
  <h3>Sample Log</h3>
  <div>
    <pre>
martin@martin-EC548AA-ABU-a1128-uk:/media/martin/LINKS/groovy-core/groovy-core$ bash ./gradlew asciidocAll
To honour the JVM settings for this build a new JVM will be forked. Please consider using the daemon: http://gradle.org/docs/1.12/userguide/gradle_daemon.html.
:buildSrc:clean UP-TO-DATE
:buildSrc:compileJava
:buildSrc:compileGroovy
:buildSrc:processResources UP-TO-DATE
:buildSrc:classes
:buildSrc:jar
:buildSrc:assemble
:buildSrc:compileTestJava UP-TO-DATE
:buildSrc:compileTestGroovy UP-TO-DATE
:buildSrc:processTestResources UP-TO-DATE
:buildSrc:testClasses UP-TO-DATE
:buildSrc:test UP-TO-DATE
:buildSrc:check UP-TO-DATE
:buildSrc:build
Using Java from /usr/lib/jvm/java-7-openjdk-i386/jre (version 1.7.0_55)
Detected development environment
:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-closures.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-differences-java.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-domain-specific-languages.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-gdk.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-getting-started.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-introduction.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-metaprogramming.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-object-orientation.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-operators.adoc
asciidoctor: WARNING: src/spec/doc/design-pattern-abstract-factory.adoc: line 1: section title out of sequence: expected level 2, got level 4
asciidoctor: WARNING: design-pattern-in-groovy.adoc: line 52: section title out of sequence: expected level 2, got level 3
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-iterator.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-loan-my-resource.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-null-object.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-pimp-my-library.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-proxy.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-singleton.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-state.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-strategy.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-template-method.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-visitor.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/grape.adoc
asciidoctor: WARNING: grape.adoc: line 28: section title out of sequence: expected levels 0 or 1, got level 2
asciidoctor: WARNING: grape.adoc: line 105: section title out of sequence: expected levels 0 or 1, got level 2
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/guide-integrating.adoc
asciidoctor: WARNING: guide-integrating.adoc: line 11: section title out of sequence: expected levels 0 or 1, got level 2
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/index.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/invokedynamic-support.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/license-contributors.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/template-engines.adoc
asciidoctor: WARNING: subprojects/groovy-templates/src/spec/doc/markup-template-engine.adoc: line 1: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: template-engines.adoc: line 145: section title out of sequence: expected level 2, got level 3
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovyc.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovyconsole.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovydoc.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovyeclipse.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovysh.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-ide.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/version-scheme.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/windows-nsis-installer.adoc
:asciidoctorAssets
:asciidocAll
:groovy-ant:asciidoctor SKIPPED
:groovy-ant:asciidoctorAssets
:groovy-ant:asciidocAll UP-TO-DATE
:groovy-bsf:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-bsf/src/spec/doc/integrating-bsf.adoc
:groovy-bsf:asciidoctorAssets
:groovy-bsf:asciidocAll
:groovy-console:asciidoctor SKIPPED
:groovy-console:asciidoctorAssets
:groovy-console:asciidocAll UP-TO-DATE
:groovy-docgenerator:asciidoctor SKIPPED
:groovy-docgenerator:asciidoctorAssets
:groovy-docgenerator:asciidocAll UP-TO-DATE
:groovy-groovydoc:asciidoctor SKIPPED
:groovy-groovydoc:asciidoctorAssets
:groovy-groovydoc:asciidocAll UP-TO-DATE
:groovy-groovysh:asciidoctor SKIPPED
:groovy-groovysh:asciidoctorAssets
:groovy-groovysh:asciidocAll UP-TO-DATE
:groovy-jmx:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-jmx/src/spec/doc/jmx.adoc
:groovy-jmx:asciidoctorAssets
:groovy-jmx:asciidocAll
:groovy-json:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-json/src/spec/doc/json-userguide.adoc
:groovy-json:asciidoctorAssets
:groovy-json:asciidocAll
:groovy-jsr223:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-jsr223/src/spec/doc/integrating-jsr223.adoc
:groovy-jsr223:asciidoctorAssets
:groovy-jsr223:asciidocAll
:groovy-nio:asciidoctor SKIPPED
:groovy-nio:asciidoctorAssets
:groovy-nio:asciidocAll UP-TO-DATE
:groovy-servlet:asciidoctor SKIPPED
:groovy-servlet:asciidoctorAssets
:groovy-servlet:asciidocAll UP-TO-DATE
:groovy-sql:asciidoctor SKIPPED
:groovy-sql:asciidoctorAssets
:groovy-sql:asciidocAll UP-TO-DATE
:groovy-swing:asciidoctor SKIPPED
:groovy-swing:asciidoctorAssets
:groovy-swing:asciidocAll UP-TO-DATE
:groovy-templates:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-templates/src/spec/doc/markup-template-engine.adoc
:groovy-templates:asciidoctorAssets
:groovy-templates:asciidocAll
:groovy-test:asciidoctor SKIPPED
:groovy-test:asciidoctorAssets
:groovy-test:asciidocAll UP-TO-DATE
:groovy-testng:asciidoctor SKIPPED
:groovy-testng:asciidoctorAssets
:groovy-testng:asciidocAll UP-TO-DATE
:groovy-xml:asciidoctor SKIPPED
:groovy-xml:asciidoctorAssets
:groovy-xml:asciidocAll UP-TO-DATE

BUILD SUCCESSFUL

Total time: 5 mins 22.43 secs
</pre>
  </div>
</div>
++++


=== Success ?

If your command log looks something like the above, then you have a valid [blue]#Groovy# installation, and you've also constructed a fresh local copy of the [blue]#Groovy# documentation. 

You can check your local copy to see if it looks good. Using the example above, you should have an *index.html* page located in +file:///media/martin/LINKS/groovy-core/target/asciidoc/index.html+ though your actual address of the index.html file will differ a little. Enter your own address as a browser address, then you should see this :

.Groovy Document Index
image::assets/img/console3.png[Groovy Document Index, align="center"] 

As you update documents, you may need to see how it looks. Following the previous steps, you can do it using the +./gradlew asciidocAll+ command, then open the *Groovy Index* page and navigate to the topic you've updated.

<<<

== Choose Where To Contribute

=== Identify Potential Topics 

Do you have a special interest, or know some areas where you have some knowledge or where your skills may be useful ? There are many areas where your expertise can be put to good use. Here's one idea.

Open the https://github.com/groovy/groovy-core/tree/master/src/spec/doc[Groovy Documentation Tree]. There are a large number of  document files, one for each core component and each separate sub-project extension within [blue]#Groovy#. These are simple text file (no funny stuff)  in a markup syntax called *asciidoc*. Document files end with *.adoc*.

'''

NOTE: This link is for documents in the core system. There are matching trees for each sub-project like json, xml, swing, etc.

'''

For an example, let's look at one document named _core-domain-specific-languages.adoc_. Confirm you are signed into *GitHub* then click the above link to see our live documentation tree. 

You'll be taken into the document set for *domain specific languages* in the live [blue]#Groovy# code base - not your own *GitHub* version. 

''' 

TIP: Remember that [blue]#Groovy# development is dynamic and changes daily.  The copy you took will become dated and will not have newer changes, additions, etc. so it's more accurate to review live [blue]#Groovy# when deciding what you'd like to do.

'''


=== Drill Down

See that module named +core-domain-specific-languages.adoc+ ?  Click on that filename.

If you review +core-domain-specific-languages.adoc+, you'll see a button marked +Raw+ at the top right. Click +Raw+ to see the actual plain text markup within the +core-domain-specific-languages.adoc+ file. It starts like this:

[source,role="console",options="nowrap"]
.core-domain-specific-languages.adoc
----
 = Domain-Specific Languages

 == Command chains

Groovy lets you omit parentheses around the arguments of a
method call for top-level statements. ``command chain'' feature extends this by allowing us to chain such
parentheses-free method calls, requiring neither parentheses around arguments, nor dots between the chained calls.
The general idea is that a call like `a b c d` will actually be equivalent to `a(b).c(d)`. This
also works with multiple arguments, closure arguments, and even named arguments. Furthermore, such command chains can
also appear on the right-hand side of assignments. Let's have a look at some examples
supported by this new syntax:

[source,groovy]
---------------------------------------------------------------------------------------------------------------
include::{projectdir}/src/spec/test/CommandChainsTest.groovy[tags=commandchain_1,indent=0]
. .
...
----

Then if you look below, you can see different topics like :

[source,role="console",options="nowrap"]
.Asciidoctor Heading One Titles
----
 == Operator overloading

(TBD)

 == Script base classes

(TBD)

 == Adding properties to numbers

(TBD)

----

Since these titles are marked as *(TBD)* or *To Be Done* they need some work.

=== Ready To Start ?

So now you know how and where to look, you can review our [blue]#Groovy# documents depending on your area of interest. Find a subject title marked something like +== Operator overloading

(TBD)
+ in one of our *.adoc* files, or whatever takes your fancy.

Then after you decide how/where to donate, register your interest in that area and claim it as yours. Read on to learn how you do that.

<<<

== Stand And Declare

=== Declare Your Interest 

To let us know you're working on a topic, it's useful to put your id, like nickname, date, etc., next to your topic. Edit the *.adoc* file directly in your own online copy of groovy-core to insert your id. After that, save the document, comment and commit the change. Finally, you issue a *PULL* request to the [blue]#Groovy# admins icon:user[] to merge your amendment back into the [blue]#Groovy# code base from your *GitHub* account. 

This way you stake a claim to a particular topic and everyone knows it's what you're working on. If someone else wants to work on that topic, they'll see your id and should avoid it. 

'''

NOTE: After you are finished writing, editing, updating and placing your changes back into the [blue]#Groovy# code base, you will need to remove your id.  

'''

==== Annotate The Topic Document

.Raw Asciidoctor Markup for a Groovy Topic
image::assets/img/console2.png[Sample Markup, align="center"] 

Here's a demo we did earlier. Notice the line +==== MarkupBuilder

(TBD)
 - assigned to JNorthr 1July14+ assigned to one of our documentation team ?

You need to do the same, to an +.adoc+ document in your own GitHub copy. Look in a folder named something like +./groovy-core/groovy-core/src/spec/doc+ to see where your topic has been discussed. Then edit it, adding your id and, if necessary, save as plain text format using the *UTF-8* character set.

'''

WARNING: We do not have a procedure yet for new topics. Can you suggest one ?

'''

If you've cloned/copied groovy-core to your local system, you can do the same thing this way :

[source,role="console",options="nowrap"]
.Add your remarks
----
cd ./groovy-core/groovy-core/src/spec/doc
edit core-domain-specific-languages.adoc
// add your id on the topic you'll document
save core-domain-specific-languages.adoc as UTF-8
----

==== Promote Your Change 

[source,role="console",options="nowrap"]
.Send your remarks back to Groovy
----
cd ./groovyCore/groovy-core/src/spec/
git status
git add src/spec/doc/core-domain-specific-languages.adoc
git commit -m 'add Builder topic to my list to be documented'
git push origin master
// provide your credentials to GitHub
----

<<<

=== Fix *GitHub*

Now your id is back in your own *GitHub* repo, you can send your change(s) back to [blue]#Groovy#. You must ask [blue]#Groovy# admin icon:user[] to merge your changes into [blue]#Groovy# from your own *GitHub* account. Go to your own *GitHub* home page and find the repository you copied from [blue]#Groovy#.

.*GitHub* Pull Request
image::assets/img/console5.png[Request Pull from Groovy Admin, align="center"] 

A merge is known as a *PULL* request because you are asking [blue]#Groovy# admin icon:user[] to *PULL* your changes back into the [blue]#Groovy# codebase. 

Click the +PULL+ button to see the next panel.

'''

IMPORTANT: Only one *PULL* request can be issued for each branch modification.

'''

+++<br />+++

.Declare New Pull Request
image::assets/img/console6.png[Request Pull from Groovy Admin, align="center"] 

Click the +New Pull Request+ button.

You will need to enter a comment and title. It helps [blue]#Groovy# admin icon:user[] to understand what's going on.

'''

<<<

=== Review Your Submission

.Confirm Pull Request
image::assets/img/console7.png[Request Pull from Groovy Admin, align="center"] 

You can review your submitted details here. See where your _commit_ statement appears ? Under that, you can see your actual changes, the line in [red]#PINK# was removed and replaced by the line shown in [green]#GREEN#. ( This sample is from a more recent declaration ).

<<<

== Asciidoctor Markup, A Review

This [blue]#Groovy# document, and most others, are written with  asciidoctor. Each time [blue]#Groovy# is rebuilt, a fresh version of all *.adoc* files are too. Visit our link:groovy-contributions.html#_success[Success] topic above to learn how to review your own  [blue]#Groovy# documents.

Here's an overview of the http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Syntax]. It's a simple markup style that comes with a Ruby Gem. The markup syantax is based on an earlier effort named asciidoc and you can read more about that original version of Asciidoc  http://www.methods.co.nz/asciidoc/userguide.html[here]. Review a http://asciidoctor.org/docs/asciidoc-writers-guide/[style guide here].

=== Why Use Asciidoctor ?

*IN* these days of fast paced application development, it's *GR8* to have a simple markup language and tool to write stuff. The asciidoctor tool is a quick performing ruby gem we can use to write up documentation and reference materials. We can write them quickly, then translate them into either +HTML+ or +Docbook+ output, and we can do this outside the [blue]#Groovy# development environment. Of course, it's an automatic feature of full [blue]#Groovy# build, but on a small scale, it's much easier to see how things look when built locally before the full-build stage.

=== Install Your Own Doctor

If you still wish to donate some expertise, but want to avoid a full [blue]#Groovy# install, it's possible to install the +asciidoctor+ tool on your own system.

In a terminal console, try  +gem install asciidoctor+ using the asciidoctor toolchain guide http://asciidoctor.org/docs/install-toolchain/[here]. 

Then you can write a simple sample plain text file using an editor ( without funny stuff or markup). Follow the syntax guide above. Then when you're ready, you can do this from a command line like  we did here to create this document. This text file is named *groovy-contributions.adoc* and and it was saved with a *UTF-8* character encoding.

After +asciidoctor+ ran, we had an output file named *groovy-contributions.html* in the same directory as the .adoc file. Since the + 
*CSS* icon:css3[] stylesheet is embedded in the .html document, you can view this result right away, though  images and javascript stuff may not be in the expected place.

+martin@EC548A:~/Desktop$ asciidoctor groovy-contributions.adoc+

If you find you've created something useful, check out our mailing lists to see how you can donate it.

'''

NOTE: http://saltnlight5.blogspot.fr/2013/08/how-to-convert-asciidoc-text-to-html.html[Converting asciidoctor markup to html] - will give Groovy people an overview of other possibilities. 

'''

.Asciidoctor References
 * http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]
 * http://asciidoctor.org/docs/asciidoc-writers-guide/[Writer's Guide]
 * http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Syntax Reference Guide]
 * http://mrhaki.blogspot.fr/2014/04/awesome-asciidoc-include-partial-parts.html[Mr Haki] explains how to insert *INCLUDE* code snippets in Asciidoc documentation.
 * http://mrhaki.blogspot.fr/2014/06/awesome-asciidoc-change-source-code.html[Mr Haki] shows how to indent source code.
 * http://mrhaki.blogspot.fr/2014/05/awesome-asciidoc-explain-code-with.html[Mr Haki] shows how to explain testcode with callouts.

<<<

== Tag Annotations

Documents benefit from the inclusion of code samples. Live tests that are part of a typical [blue]#Groovy# build are ideal candidates. We know that if a build succeeds, then all it's tests were successful too. Therefore samples from live tests can improve our documents.

Before we get into the topic of test cases, here's a *heads-up* on how we do it using some asciidoctor features.

=== Asciidoctor Includes and Tags

Asciidoctor can identify parts of files for inclusion. Use the *include* statement to insert source material from another file. The *include* syntax offers a nice way to choose a piece of the file to include. The *tag* declaration identifies the piece. 

'''

TIP: *tag* names follow a convention of {name of script}_{name of method}_{incrementing number of this test within all tests}[]

'''

Given an asciidoctor declaration like this :

.Sample BuilderSupportTest Include
....
 === Sample Asciidoc BuilderSupportTest Tag

 [source,groovy]
 .BuilderSupportTest.groovy Listing
 ----
 include::BuilderSupportTest.groovy[tags=BuilderSupportTest_add_node_with_value_object4]
 ----
....

would only insert source statements between the +BuilderSupportTest_add_node_with_value_object4+ tag start and end as follows : 

image::assets/img/example19.png[BuilderSupportTest.groovy Listing] 

from this :

.BuilderSupportTest.groovy
....
// tag::BuilderSupportTest_add_node_with_value_object4[]
        // simple node with one attribute
        def sb3 = new BuilderSupportTest()
        def node3 = sb3.foo(name:'value')
        
        // node type 3 creation with map as name/value pair
        assert sb3.log == ['cn3','foo', 'name','value', 'nc',null,'x']
// end::BuilderSupportTest_add_node_with_value_object4[]
....

NOTE: +//+ characters identify the remainder of a line as remarks.

'''

Asciidoctor tags are simply remarks / comments and so are invisible at build time. They're declared in pairs as a tag set. The *tag* keyword preceeds the tag name +BuilderSupportTest_add_node_with_value_object4+ followed by the asciidoc required tag ending of +[]+

+// tag::+ says start using text after this line.

+// end::+ says stop using text before this line.


Does this make sense ? It's possible to grab some of a live test and insert it into our document. It's always a valid example 'cos the build succeeded [red]#icon:exclamation[]#

icon:thumbs-up[] Ok, let's review test cases next. 

<<<

== Examine Test Cases

=== Review Current Tests

Review the https://github.com/groovy/groovy-core/tree/master/src/spec/test[Test Case] folder. There may already be tests that cover your area of interest. Some were written before tag standards  came into existence. It might be as simple as adding asciidoctor tags around a test method.

==== Change Known Test Cases 

Here's an existing test case from +groovy-core/src/spec/test/builder/CliBuilderTest.groovy+ :

Typical class comments preceed the class declaration with author attribution :

[source,role="console",options="nowrap"]
.CliBuilder Test Class
----
/**
* Tests for CliBuilder. The tests directly in this file are specific
* to CliBuilder. Functionality in common with other Builders
* is tested in the parent class.
*
* @author Groovy Documentation Community
*/
----

Earlier test cases did not use *GroovyTestCase* as a basis, though more recent test cases do : + 

[source,role="console",options="nowrap"]
.Class
----
class CliBuilderTest extends GroovyTestCase {
----

[source,role="console",options="nowrap"]
.Sample Test method
----
 void testObjectNotDefined() {

	// tag::clibuilder_nullobject1[]
	CliBuilder clibuilder;

	// clibuilder should be null when not initialized
	assert clibuilder == null;

	// end::clibuilder_nullobject1[]

} // end of method
----

[source,role="console",options="nowrap"]
.Sample Result
----
	CliBuilder clibuilder;

	// clibuilder should be null when not initialized
	assert clibuilder == null;
----

TIP: The *assert* statement should have a remark before it. It should explain say why the test should succeed - *not* why it would fail icon:exclamation[]

'''

=== Add New Test Cases 

It's outside the scope of this document, though if you feel something is missing in our test coverage, please raise a question. Our mailing lists are an ideal place to ask questions and receive suggestions about how you can contribute new test cases. Everyone says more tests improve product quality. Can you think of any tests  we missed ?

==== Copyright Notice

It's always useful to identify the license terms for use with any asset you create or amend. A copyright statement does just that. Here's a sample copyright often used when doing test cases :

[source,role="console",options="nowrap"]
.Copyright Notice
----
/*
* Copyright 2014 the original author or authors.
*
* Licensed 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.
*/
----


=== Forget Test Cases ?

Well, why not ? It's not critical to have samples of test stuff. Plenty of great documentation does not require any reference to tests or the content may not even be about code, logic, tests, scripts.<commit_msg>Documentation: update "Copyright Notice" section<commit_after>= Groovy Contributions
 
++++
<link rel="stylesheet" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.11.0/themes/blitzer/jquery-ui.css">
++++

<<<

== Help !

A key area we've been working on for a while is our new [blue]#Groovy# documentation. <NAME> has detailed how you can help us author some sections of the documentation. http://blog.cacoethes.co.uk/groovyandgrails/contributing-to-the-groovy-documentation[Read his post here]. 

Like Peter, you can dedicate a bit of your time on a topic of your choice, to further deepen your understanding of a particular area of [blue]#Groovy# and share your knowledge with your peers.

We really look forward to your contributions!

.Your Contributions
****
The [blue]#Groovy# core team is a very small team, compared to the huge team a company like Oracle puts behind Java and the JVM, or Microsoft behind its languages and the .Net platform. So all contributions, in any form, do count, and are important to the success and evolution of the [blue]#Groovy# language.
****

<<<

== Contributions Walk-Thru 

.Prerequisites
 - [*] Working internet connection
 - [ ] Familiarity with computer directory organization, folders, sub-directories and structures of hierarchies
 - [ ] Have a GitHub Account and familiarity with concepts about code repositories - also called *repo-s*
 - [ ] Knowledge of computer terminal command line
 - [ ] Installed *GIT* tool
 - [ ] Plain text editor like TEXTEDIT, NOTEPAD, gedit, Leafpad; - a tool that does *NOT* include markup like bold,italics, etc. and saves file in the *UTF-8* character set
 - [ ] Be familiar with http://asciidoctor.org/docs/user-manual/[Asciidoctor markup] and the  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[syntax reference guide] ( more notes are listed below ).
 - [ ] Optionally - have the http://asciidoctor.org/docs/install-toolchain/[*asciidoctor* toolchain] installed on your local system
 - [ ] Be familiar with unit testing of individual programs; it may be necessary to write some new test cases for groovy modules. ( _Optional_ )
 - [ ] Enthusiasm and nice writing style  

'''

IMPORTANT: It's *NOT* necessary to have [blue]#Groovy# installed on your local system to be able to write documentation.

'''

=== Join Us !

Please join any of our mailing lists at http://groovy-lang.org/mailing-lists.html[http://groovy-lang.org/mailing-lists.html]. 

Whether you are a user, developer, or enthusiast, we have a choice of mailing lists you may find appealing. Ask and get answers for questions about the [blue]#Groovy# eco-system.

You can find live icon:twitter[] https://twitter.com/hashtag/groovylang[#groovylang] feeds for up-to-the-minute news.

'''


=== Where is Groovy ?

Open source developers often need somewhere to keep all their assets. These assets are typically stored in a repository somewhere on the internet. icon:github[link="https://github.com/"] https://github.com/[*GitHub*] is one such storage facility. At *[blue]#Groovy#*, we keep https://github.com/groovy/groovy-core[our _source code_ here]. 

Visit our *[blue]#Groovy#* information portal at image:assets/img/groovy.png[Groovy Website, 60, 30, link="http://groovy-lang.org/"] 

We build *[blue]#Groovy#* continuously at image:assets/img/teamcity.png[TeamCity, 73, 20, link="http://ci.groovy-lang.org/"]. Log in as a guest.


=== How Do I Contribute ?

There are two paths to contribute : 

For small things, you can change the relevant document on-line, within the *GitHub* system. For spelling or punctuation typos, broken language, etc, you can edit the document live from within Github. We mention this approach for small contributions that don't require us to run the tests / create or update new tests. link:#_quick_fixes[Follow this trail.]

For larger contributions, it's more likely you'll need to copy [blue]#Groovy# into your own work environment, then link:#_take_the_long_way_home[Take The Long Way Home.]

== Quick Fixes To Groovy

Sometimes, you may spot a tiny flaw in our otherwise perfect product. It's bugging you, so you want to fix it quickly without all the trouble of porting [blue]#Groovy# to your own system. Can it be done ?

[red yellow-background big]*Sure icon:exclamation[]*

Let's say you need to fix the [blue]#Groovy# README.adoc file in https://github.com/groovy/groovy-core[https://github.com/groovy/groovy-core] - our core location.

'''

IMPORTANT: Only use this way to fix small stuff like spelling bits. Otherwise your fix may avoid our indepth testing process [red yellow-background big]*:-(*

'''

Click the core location address to get here :

.Groovy Core Page
image::assets/img/example15.png[Details, align="center"] 

Your view should look like this, except it will say +groovy / groovy-core+ ( this view was from another example and has the wrong location name ). Confirm you are viewing +groovy / groovy-core+ then click the name of the resource to edit, in this case *README.adoc*. The following view opens.

'''

.README.adoc View
image::assets/img/example16.png[Details, align="center", link="https://github.com/groovy/groovy-core/blob/master/README.adoc"] 

This view is the current content of the *README* file. You can see ( but not edit ) the raw text by clicking the +RAW+ button. But for this example, you want to change some text. The red arrow points to the editor *PENCIL*. Click that to open an editable version of this page. See below.


'''

.Groovy-core/README.adoc page
image::assets/img/example17.png[Details, align="center", link="https://github.com/groovy/groovy-core/blob/master/README.adoc"] 

Confirm you're on the correct page ( blue square ). Then on line 80, after the words _Continuous Integration_ add the word _Server_

'''

Then add more details like this :

.Ready To Roll
image::assets/img/example18.png[Details, align="center"] 

In the box marked *Commit changes* add a short descriptive title and add more detail below. Then click [white green-background big]*Commit changes* button to seal the deal. Easy-peasy icon:exclamation[]  icon:smile[]

<<<

== Take The Long Way Home

This way needs more work on your part though it it is more rewarding too.

First we look at the home of [blue]#Groovy# . Then we review the structure and important items. After that we pick up the story at link:#_getting_started[Getting Started.]

=== Notes About GitHub

At *[blue]#Groovy#*, we keep https://github.com/groovy/groovy-core[our _source code_ here].

==== GitHub Information

++++
<div id="accordion2">
  <h3>Typical Workflow Steps</h3>
  <div>
<ul>
<li>join GitHub
<li>sign in to your GitHub account
<li>locate the groovy code base
<li>make a copy ( FORK ) of it into your own online GitHub account
 <li>make a local copy ( CLONE ) from your own online GitHub account
 <li>create a new feature branch
 <li>switch to your new feature branch
 <li>build/amend the documents
 <li>provide screen images if needed
 <li>provide test cases to match your documentation
 <li>build and test everything
 <li>commit your changes
 <li>switch to your master branch
 <li>merge your branch full of changes into the master branch
 <li>send ( PUSH ) your changes back to your own online account
 <li>ask the groovy admins to include ( PULL ) your changes in the groovy code base
</ul>
  </div>

  <h3>Git Clients</h3>
  <div>
<ul>
<li><a href="http://git-scm.com/downloads/guis" target="_blank">Git Client GUIs for All Platforms</a></li>
<li><a href="http://docs.oseems.com/general/operatingsystem/ubuntu/install-git-client" target="_blank">Git Client for Ubuntu</a></li>
<li><a href="http://msysgit.github.io/" target="_blank">Git Client for Windows</a></li>
</ul>
</div>

  <h3>Git References</h3>
  <div>
<ul>
<li><a href="https://help.github.com/articles/set-up-git" target="_blank">Setup Git</a></li>
<li><a href="https://help.github.com/articles/signing-up-for-a-new-github-account" target="_blank">Sign-up for a new Github account</a></li>
<li><a href="https://help.github.com/articles/fork-a-repo" target="_blank">Fork a repo</a></li>
<li><a href="http://gitref.org/branching/" target="_blank">Git Branching and Merging</a></li>
<li><a href="https://gun.io/blog/how-to-github-fork-branch-and-pull-request/" target="_blank">Git Rebase</a></li>
<li><a href="http://www.markjberger.com/git-tips-for-beginners/" target="_blank">Tips for beginners</a></li>
<li><a href="http://blog.guy.ht/2010/12/using-branches-to-manage-documentation-on-github/" target="_blank">Manage With Branches</a></li>
</ul>
</div>


</div>
++++

+++<br />+++

'''


=== Groovy Directory Structure

From here on, we've assumed you have logged into your own *GitHub* account. 

==== Visit Groovy Core Repository on GitHub

Open a web browser, then use address https://github.com/groovy/groovy-core[https://github.com/groovy/groovy-core] to review the [blue]#Groovy# code base. It looks like this :

.Groovy Core on *Github* icon:github[link="https://github.com/groovy/groovy-core", window="_blank"]
image::assets/img/github4.png[Groovy Core Repository on GitHub, 495, 436, link="https://github.com/groovy/groovy-core",align="center"] 

There are a number of folders within the [blue]#Groovy# code base. The most important folders are */src* and */subprojects* as these folders hold the base code and scripts for [blue]#Groovy#.

==== The +/src+ Folder

The core of [blue]#Groovy# lives within this folder. Here is where we find a variety of artifacts, scripts, tests, resources, images, etc. 

.Groovy Core Source Folder on *Github* icon:github[link="https://github.com/groovy/groovy-core/tree/master/src", window="_blank"]
image::assets/img/github1.png[Groovy Core Source, 497, 313, link="https://github.com/groovy/groovy-core/tree/master/src",align="center"] 


==== The +/subprojects+ Folder

[blue]#Groovy# has many additional features that are not part of the core system. Source code for these added features can be found in the *subprojects* folder. It looks something like this :

.Groovy Core Sub-Projects Source Folder on *Github*  icon:github[link="https://github.com/groovy/groovy-core/tree/master/subprojects", window="_blank"]
image::assets/img/github2.png[Groovy Core Source, 499, 397, link="https://github.com/groovy/groovy-core/tree/master/subprojects",align="center"] 

==== The Documentation Folder

Within each */src* and */subproject/src* is a */spec* documents folder that exists, or will soon be created. 

.Groovy Document Specifications Folder on *Github*  icon:github[link="https://github.com/groovy/groovy-core/tree/master/src/spec", window="_blank"]
image::assets/img/github3.png[Groovy Documents Source, 500, 185, link="https://github.com/groovy/groovy-core/tree/master/src/spec",align="center"] 

The two most useful folders here are */doc* and */test*. These two folders hold our documents and test cases.

===== Documents

All of our documents are written as typical text files encoded as *UTF-8* characters. The text is styled in the markup syntax known as http://asciidoctor.org/docs/user-manual/[*asciidoc*] or http://asciidoctor.org/docs/user-manual/[*asciidoctor*] ( the more recent version ). These text files have a filename suffix designation of *.adoc*.

.Groovy Documentation Folder on *Github*
image::assets/img/github5.png[Groovy Documents Folder, 501, 170, link="https://github.com/groovy/groovy-core/tree/master/src/spec/doc",align="center"] 

===== Test Cases

To prove that [blue]#Groovy# modules work as expected, we often construct test cases that exercise code logic. These test cases are actually [blue]#Groovy# scripts that reside in the */test* folder.

.Groovy Core Test Folder on *Github* icon:github[link="https://github.com/groovy/groovy-core/tree/master/src/spec/test", window="_blank"]
image::assets/img/github6.png[Groovy Testcase Folder, 505, 303, link="https://github.com/groovy/groovy-core/tree/master/src/spec/test",align="center"] 

If you would like to know more about writing effective test cases, please http://groovy-lang.org/testing.html[review this link].
 
 
==== Wrap Up

Ok, that's a quick review of our [blue]#Groovy# code base, the directory/folder structure and important bits. It _should_ give you a starting point  to explore [blue]#Groovy# icon:thumbs-up-alt[]

'''

<<<

== Getting Started
 
Let's assume you've logged into your *GitHub* account.

.*GitHub* Home Panel
image::assets/img/githubhomepanel.png[Github Home Panel, align="center"] 
 
This is the typical panel you use to work with *GitHub*. It has a variety of things you can do. You'll need to search for the [blue]#Groovy# repository, so look at the top of this panel. See that field named +Search or type a command+ ? Let's use  that to icon:search[].

'''

=== Make [blue]#Groovy# Your Own 

.Search icon:search[] on *GitHub* for Groovy-Core
image::assets/img/githubsearch.png[Github Search Feature,align="center"] 

Ok, let's look for the *groovy-core* repository. In the field named +Search or type a command+ enter *groovy-core* then click +Search+. You should see a repository named *groovy/groovy-core* so click that to visit the home of [blue]#Groovy#.

''' 

.Fork Groovy Core on *GitHub*
image::assets/img/githubfork.png[Fork The Code, 541, 156, link="https://github.com/groovy/groovy-core",align="center"] 

So you can work on your own version of [blue]#Groovy#, you'll need to make a copy of it. This copy is placed in your own *GitHub* account under your credentials. This task of making a copy is known as *Fork* -ing.

Check you're logged into your own *GitHub* account before you start to search.

Fork the https://github.com/groovy/groovy-core[groovy/groovy-core] repository on *GitHub* to your own *GitHub* account. Click the +Fork+ button while on the *groovy/groovy-core* panel. When you look at your own *GitHub* home page, you'll see the list of your forked repos and any new repos you make.

.Fork Groovy Core on *GitHub*
image::assets/img/repolist.png[List of Repos, link="https://github.com/groovy/groovy-core",align="center"] 

You now have your own version of [blue]#Groovy# in your *GitHub* account on the remote server. Next, you'll want to bring a copy of it onto your local system. It's easier to work with documents and test cases that way.

'''

TIP: See this https://gun.io/blog/how-to-github-fork-branch-and-pull-request/[gun.io] tutorial covering fork, branch, pull tactics.

'''

=== Terminally Yours

[source,role="console",options="nowrap"]
.Commands
----
Open a terminal/command prompt
Make a folder to hold your copy of Groovy; for now, create a folder named groovy-core
Change directories ( cd ) into your groovy-core version of the directory.
----

=== Copy [blue]#Groovy#

Clone/copy your forked repository from your own *GitHub* account to your local system, then check which version of the *Java* runtime environment you have. 

[source,role="console",options="nowrap"]
.Command - ( replace xxxxx with your *GitHub* nickname )
----
git clone https://github.com/xxxxxx/groovy-core.git
cd groovy-core
java -version
----

.Terminal Console Afterward
image::assets/img/console1.png[List of Commands, align="center"] 

If your java version is earlier than 1.6 you might not be able to do much testing. If it's recent then change directories into the *groovy-core* folder. 

'''

=== Check Your Installation

To make sure you can build and test your [blue]#Groovy# version, try to build just the [blue]#Groovy# document suite. 

.Run one of these commands depending on your operating system:
 * +bash ./gradlew asciidocAll+ on Linux/Ubuntu 
 * +gradlew asciidocAll+ on Windows
 * +./gradlew asciidocAll+ for Apple

Your sample log might look like this :

++++
<div id="accordion">
  <h3>Sample Log</h3>
  <div>
    <pre>
martin@martin-EC548AA-ABU-a1128-uk:/media/martin/LINKS/groovy-core/groovy-core$ bash ./gradlew asciidocAll
To honour the JVM settings for this build a new JVM will be forked. Please consider using the daemon: http://gradle.org/docs/1.12/userguide/gradle_daemon.html.
:buildSrc:clean UP-TO-DATE
:buildSrc:compileJava
:buildSrc:compileGroovy
:buildSrc:processResources UP-TO-DATE
:buildSrc:classes
:buildSrc:jar
:buildSrc:assemble
:buildSrc:compileTestJava UP-TO-DATE
:buildSrc:compileTestGroovy UP-TO-DATE
:buildSrc:processTestResources UP-TO-DATE
:buildSrc:testClasses UP-TO-DATE
:buildSrc:test UP-TO-DATE
:buildSrc:check UP-TO-DATE
:buildSrc:build
Using Java from /usr/lib/jvm/java-7-openjdk-i386/jre (version 1.7.0_55)
Detected development environment
:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-closures.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-differences-java.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-domain-specific-languages.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-gdk.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-getting-started.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-introduction.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-metaprogramming.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-object-orientation.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/core-operators.adoc
asciidoctor: WARNING: src/spec/doc/design-pattern-abstract-factory.adoc: line 1: section title out of sequence: expected level 2, got level 4
asciidoctor: WARNING: design-pattern-in-groovy.adoc: line 52: section title out of sequence: expected level 2, got level 3
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-iterator.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-loan-my-resource.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-null-object.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-pimp-my-library.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-proxy.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-singleton.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-state.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-strategy.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-template-method.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/design-pattern-visitor.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/grape.adoc
asciidoctor: WARNING: grape.adoc: line 28: section title out of sequence: expected levels 0 or 1, got level 2
asciidoctor: WARNING: grape.adoc: line 105: section title out of sequence: expected levels 0 or 1, got level 2
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/guide-integrating.adoc
asciidoctor: WARNING: guide-integrating.adoc: line 11: section title out of sequence: expected levels 0 or 1, got level 2
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/index.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/invokedynamic-support.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/license-contributors.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/template-engines.adoc
asciidoctor: WARNING: subprojects/groovy-templates/src/spec/doc/markup-template-engine.adoc: line 1: section title out of sequence: expected level 2, got level 3
asciidoctor: WARNING: template-engines.adoc: line 145: section title out of sequence: expected level 2, got level 3
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovyc.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovyconsole.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovydoc.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovyeclipse.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-groovysh.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/tools-ide.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/version-scheme.adoc
Rendering /media/martin/LINKS/groovy-core/groovy-core/src/spec/doc/windows-nsis-installer.adoc
:asciidoctorAssets
:asciidocAll
:groovy-ant:asciidoctor SKIPPED
:groovy-ant:asciidoctorAssets
:groovy-ant:asciidocAll UP-TO-DATE
:groovy-bsf:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-bsf/src/spec/doc/integrating-bsf.adoc
:groovy-bsf:asciidoctorAssets
:groovy-bsf:asciidocAll
:groovy-console:asciidoctor SKIPPED
:groovy-console:asciidoctorAssets
:groovy-console:asciidocAll UP-TO-DATE
:groovy-docgenerator:asciidoctor SKIPPED
:groovy-docgenerator:asciidoctorAssets
:groovy-docgenerator:asciidocAll UP-TO-DATE
:groovy-groovydoc:asciidoctor SKIPPED
:groovy-groovydoc:asciidoctorAssets
:groovy-groovydoc:asciidocAll UP-TO-DATE
:groovy-groovysh:asciidoctor SKIPPED
:groovy-groovysh:asciidoctorAssets
:groovy-groovysh:asciidocAll UP-TO-DATE
:groovy-jmx:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-jmx/src/spec/doc/jmx.adoc
:groovy-jmx:asciidoctorAssets
:groovy-jmx:asciidocAll
:groovy-json:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-json/src/spec/doc/json-userguide.adoc
:groovy-json:asciidoctorAssets
:groovy-json:asciidocAll
:groovy-jsr223:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-jsr223/src/spec/doc/integrating-jsr223.adoc
:groovy-jsr223:asciidoctorAssets
:groovy-jsr223:asciidocAll
:groovy-nio:asciidoctor SKIPPED
:groovy-nio:asciidoctorAssets
:groovy-nio:asciidocAll UP-TO-DATE
:groovy-servlet:asciidoctor SKIPPED
:groovy-servlet:asciidoctorAssets
:groovy-servlet:asciidocAll UP-TO-DATE
:groovy-sql:asciidoctor SKIPPED
:groovy-sql:asciidoctorAssets
:groovy-sql:asciidocAll UP-TO-DATE
:groovy-swing:asciidoctor SKIPPED
:groovy-swing:asciidoctorAssets
:groovy-swing:asciidocAll UP-TO-DATE
:groovy-templates:asciidoctor
Rendering /media/martin/LINKS/groovy-core/groovy-core/subprojects/groovy-templates/src/spec/doc/markup-template-engine.adoc
:groovy-templates:asciidoctorAssets
:groovy-templates:asciidocAll
:groovy-test:asciidoctor SKIPPED
:groovy-test:asciidoctorAssets
:groovy-test:asciidocAll UP-TO-DATE
:groovy-testng:asciidoctor SKIPPED
:groovy-testng:asciidoctorAssets
:groovy-testng:asciidocAll UP-TO-DATE
:groovy-xml:asciidoctor SKIPPED
:groovy-xml:asciidoctorAssets
:groovy-xml:asciidocAll UP-TO-DATE

BUILD SUCCESSFUL

Total time: 5 mins 22.43 secs
</pre>
  </div>
</div>
++++


=== Success ?

If your command log looks something like the above, then you have a valid [blue]#Groovy# installation, and you've also constructed a fresh local copy of the [blue]#Groovy# documentation. 

You can check your local copy to see if it looks good. Using the example above, you should have an *index.html* page located in +file:///media/martin/LINKS/groovy-core/target/asciidoc/index.html+ though your actual address of the index.html file will differ a little. Enter your own address as a browser address, then you should see this :

.Groovy Document Index
image::assets/img/console3.png[Groovy Document Index, align="center"] 

As you update documents, you may need to see how it looks. Following the previous steps, you can do it using the +./gradlew asciidocAll+ command, then open the *Groovy Index* page and navigate to the topic you've updated.

<<<

== Choose Where To Contribute

=== Identify Potential Topics 

Do you have a special interest, or know some areas where you have some knowledge or where your skills may be useful ? There are many areas where your expertise can be put to good use. Here's one idea.

Open the https://github.com/groovy/groovy-core/tree/master/src/spec/doc[Groovy Documentation Tree]. There are a large number of  document files, one for each core component and each separate sub-project extension within [blue]#Groovy#. These are simple text file (no funny stuff)  in a markup syntax called *asciidoc*. Document files end with *.adoc*.

'''

NOTE: This link is for documents in the core system. There are matching trees for each sub-project like json, xml, swing, etc.

'''

For an example, let's look at one document named _core-domain-specific-languages.adoc_. Confirm you are signed into *GitHub* then click the above link to see our live documentation tree. 

You'll be taken into the document set for *domain specific languages* in the live [blue]#Groovy# code base - not your own *GitHub* version. 

''' 

TIP: Remember that [blue]#Groovy# development is dynamic and changes daily.  The copy you took will become dated and will not have newer changes, additions, etc. so it's more accurate to review live [blue]#Groovy# when deciding what you'd like to do.

'''


=== Drill Down

See that module named +core-domain-specific-languages.adoc+ ?  Click on that filename.

If you review +core-domain-specific-languages.adoc+, you'll see a button marked +Raw+ at the top right. Click +Raw+ to see the actual plain text markup within the +core-domain-specific-languages.adoc+ file. It starts like this:

[source,role="console",options="nowrap"]
.core-domain-specific-languages.adoc
----
 = Domain-Specific Languages

 == Command chains

Groovy lets you omit parentheses around the arguments of a
method call for top-level statements. ``command chain'' feature extends this by allowing us to chain such
parentheses-free method calls, requiring neither parentheses around arguments, nor dots between the chained calls.
The general idea is that a call like `a b c d` will actually be equivalent to `a(b).c(d)`. This
also works with multiple arguments, closure arguments, and even named arguments. Furthermore, such command chains can
also appear on the right-hand side of assignments. Let's have a look at some examples
supported by this new syntax:

[source,groovy]
---------------------------------------------------------------------------------------------------------------
include::{projectdir}/src/spec/test/CommandChainsTest.groovy[tags=commandchain_1,indent=0]
. .
...
----

Then if you look below, you can see different topics like :

[source,role="console",options="nowrap"]
.Asciidoctor Heading One Titles
----
 == Operator overloading

(TBD)

 == Script base classes

(TBD)

 == Adding properties to numbers

(TBD)

----

Since these titles are marked as *(TBD)* or *To Be Done* they need some work.

=== Ready To Start ?

So now you know how and where to look, you can review our [blue]#Groovy# documents depending on your area of interest. Find a subject title marked something like +== Operator overloading

(TBD)
+ in one of our *.adoc* files, or whatever takes your fancy.

Then after you decide how/where to donate, register your interest in that area and claim it as yours. Read on to learn how you do that.

<<<

== Stand And Declare

=== Declare Your Interest 

To let us know you're working on a topic, it's useful to put your id, like nickname, date, etc., next to your topic. Edit the *.adoc* file directly in your own online copy of groovy-core to insert your id. After that, save the document, comment and commit the change. Finally, you issue a *PULL* request to the [blue]#Groovy# admins icon:user[] to merge your amendment back into the [blue]#Groovy# code base from your *GitHub* account. 

This way you stake a claim to a particular topic and everyone knows it's what you're working on. If someone else wants to work on that topic, they'll see your id and should avoid it. 

'''

NOTE: After you are finished writing, editing, updating and placing your changes back into the [blue]#Groovy# code base, you will need to remove your id.  

'''

==== Annotate The Topic Document

.Raw Asciidoctor Markup for a Groovy Topic
image::assets/img/console2.png[Sample Markup, align="center"] 

Here's a demo we did earlier. Notice the line +==== MarkupBuilder

(TBD)
 - assigned to JNorthr 1July14+ assigned to one of our documentation team ?

You need to do the same, to an +.adoc+ document in your own GitHub copy. Look in a folder named something like +./groovy-core/groovy-core/src/spec/doc+ to see where your topic has been discussed. Then edit it, adding your id and, if necessary, save as plain text format using the *UTF-8* character set.

'''

WARNING: We do not have a procedure yet for new topics. Can you suggest one ?

'''

If you've cloned/copied groovy-core to your local system, you can do the same thing this way :

[source,role="console",options="nowrap"]
.Add your remarks
----
cd ./groovy-core/groovy-core/src/spec/doc
edit core-domain-specific-languages.adoc
// add your id on the topic you'll document
save core-domain-specific-languages.adoc as UTF-8
----

==== Promote Your Change 

[source,role="console",options="nowrap"]
.Send your remarks back to Groovy
----
cd ./groovyCore/groovy-core/src/spec/
git status
git add src/spec/doc/core-domain-specific-languages.adoc
git commit -m 'add Builder topic to my list to be documented'
git push origin master
// provide your credentials to GitHub
----

<<<

=== Fix *GitHub*

Now your id is back in your own *GitHub* repo, you can send your change(s) back to [blue]#Groovy#. You must ask [blue]#Groovy# admin icon:user[] to merge your changes into [blue]#Groovy# from your own *GitHub* account. Go to your own *GitHub* home page and find the repository you copied from [blue]#Groovy#.

.*GitHub* Pull Request
image::assets/img/console5.png[Request Pull from Groovy Admin, align="center"] 

A merge is known as a *PULL* request because you are asking [blue]#Groovy# admin icon:user[] to *PULL* your changes back into the [blue]#Groovy# codebase. 

Click the +PULL+ button to see the next panel.

'''

IMPORTANT: Only one *PULL* request can be issued for each branch modification.

'''

+++<br />+++

.Declare New Pull Request
image::assets/img/console6.png[Request Pull from Groovy Admin, align="center"] 

Click the +New Pull Request+ button.

You will need to enter a comment and title. It helps [blue]#Groovy# admin icon:user[] to understand what's going on.

'''

<<<

=== Review Your Submission

.Confirm Pull Request
image::assets/img/console7.png[Request Pull from Groovy Admin, align="center"] 

You can review your submitted details here. See where your _commit_ statement appears ? Under that, you can see your actual changes, the line in [red]#PINK# was removed and replaced by the line shown in [green]#GREEN#. ( This sample is from a more recent declaration ).

<<<

== Asciidoctor Markup, A Review

This [blue]#Groovy# document, and most others, are written with  asciidoctor. Each time [blue]#Groovy# is rebuilt, a fresh version of all *.adoc* files are too. Visit our link:groovy-contributions.html#_success[Success] topic above to learn how to review your own  [blue]#Groovy# documents.

Here's an overview of the http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor Syntax]. It's a simple markup style that comes with a Ruby Gem. The markup syantax is based on an earlier effort named asciidoc and you can read more about that original version of Asciidoc  http://www.methods.co.nz/asciidoc/userguide.html[here]. Review a http://asciidoctor.org/docs/asciidoc-writers-guide/[style guide here].

=== Why Use Asciidoctor ?

*IN* these days of fast paced application development, it's *GR8* to have a simple markup language and tool to write stuff. The asciidoctor tool is a quick performing ruby gem we can use to write up documentation and reference materials. We can write them quickly, then translate them into either +HTML+ or +Docbook+ output, and we can do this outside the [blue]#Groovy# development environment. Of course, it's an automatic feature of full [blue]#Groovy# build, but on a small scale, it's much easier to see how things look when built locally before the full-build stage.

=== Install Your Own Doctor

If you still wish to donate some expertise, but want to avoid a full [blue]#Groovy# install, it's possible to install the +asciidoctor+ tool on your own system.

In a terminal console, try  +gem install asciidoctor+ using the asciidoctor toolchain guide http://asciidoctor.org/docs/install-toolchain/[here]. 

Then you can write a simple sample plain text file using an editor ( without funny stuff or markup). Follow the syntax guide above. Then when you're ready, you can do this from a command line like  we did here to create this document. This text file is named *groovy-contributions.adoc* and and it was saved with a *UTF-8* character encoding.

After +asciidoctor+ ran, we had an output file named *groovy-contributions.html* in the same directory as the .adoc file. Since the + 
*CSS* icon:css3[] stylesheet is embedded in the .html document, you can view this result right away, though  images and javascript stuff may not be in the expected place.

+martin@EC548A:~/Desktop$ asciidoctor groovy-contributions.adoc+

If you find you've created something useful, check out our mailing lists to see how you can donate it.

'''

NOTE: http://saltnlight5.blogspot.fr/2013/08/how-to-convert-asciidoc-text-to-html.html[Converting asciidoctor markup to html] - will give Groovy people an overview of other possibilities. 

'''

.Asciidoctor References
 * http://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]
 * http://asciidoctor.org/docs/asciidoc-writers-guide/[Writer's Guide]
 * http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Syntax Reference Guide]
 * http://mrhaki.blogspot.fr/2014/04/awesome-asciidoc-include-partial-parts.html[Mr Haki] explains how to insert *INCLUDE* code snippets in Asciidoc documentation.
 * http://mrhaki.blogspot.fr/2014/06/awesome-asciidoc-change-source-code.html[Mr Haki] shows how to indent source code.
 * http://mrhaki.blogspot.fr/2014/05/awesome-asciidoc-explain-code-with.html[Mr Haki] shows how to explain testcode with callouts.

<<<

== Tag Annotations

Documents benefit from the inclusion of code samples. Live tests that are part of a typical [blue]#Groovy# build are ideal candidates. We know that if a build succeeds, then all it's tests were successful too. Therefore samples from live tests can improve our documents.

Before we get into the topic of test cases, here's a *heads-up* on how we do it using some asciidoctor features.

=== Asciidoctor Includes and Tags

Asciidoctor can identify parts of files for inclusion. Use the *include* statement to insert source material from another file. The *include* syntax offers a nice way to choose a piece of the file to include. The *tag* declaration identifies the piece. 

'''

TIP: *tag* names follow a convention of {name of script}_{name of method}_{incrementing number of this test within all tests}[]

'''

Given an asciidoctor declaration like this :

.Sample BuilderSupportTest Include
....
 === Sample Asciidoc BuilderSupportTest Tag

 [source,groovy]
 .BuilderSupportTest.groovy Listing
 ----
 include::BuilderSupportTest.groovy[tags=BuilderSupportTest_add_node_with_value_object4]
 ----
....

would only insert source statements between the +BuilderSupportTest_add_node_with_value_object4+ tag start and end as follows : 

image::assets/img/example19.png[BuilderSupportTest.groovy Listing] 

from this :

.BuilderSupportTest.groovy
....
// tag::BuilderSupportTest_add_node_with_value_object4[]
        // simple node with one attribute
        def sb3 = new BuilderSupportTest()
        def node3 = sb3.foo(name:'value')
        
        // node type 3 creation with map as name/value pair
        assert sb3.log == ['cn3','foo', 'name','value', 'nc',null,'x']
// end::BuilderSupportTest_add_node_with_value_object4[]
....

NOTE: +//+ characters identify the remainder of a line as remarks.

'''

Asciidoctor tags are simply remarks / comments and so are invisible at build time. They're declared in pairs as a tag set. The *tag* keyword preceeds the tag name +BuilderSupportTest_add_node_with_value_object4+ followed by the asciidoc required tag ending of +[]+

+// tag::+ says start using text after this line.

+// end::+ says stop using text before this line.


Does this make sense ? It's possible to grab some of a live test and insert it into our document. It's always a valid example 'cos the build succeeded [red]#icon:exclamation[]#

icon:thumbs-up[] Ok, let's review test cases next. 

<<<

== Examine Test Cases

=== Review Current Tests

Review the https://github.com/groovy/groovy-core/tree/master/src/spec/test[Test Case] folder. There may already be tests that cover your area of interest. Some were written before tag standards  came into existence. It might be as simple as adding asciidoctor tags around a test method.

==== Change Known Test Cases 

Here's an existing test case from +groovy-core/src/spec/test/builder/CliBuilderTest.groovy+ :

Typical class comments preceed the class declaration with author attribution :

[source,role="console",options="nowrap"]
.CliBuilder Test Class
----
/**
* Tests for CliBuilder. The tests directly in this file are specific
* to CliBuilder. Functionality in common with other Builders
* is tested in the parent class.
*
* @author Groovy Documentation Community
*/
----

Earlier test cases did not use *GroovyTestCase* as a basis, though more recent test cases do : + 

[source,role="console",options="nowrap"]
.Class
----
class CliBuilderTest extends GroovyTestCase {
----

[source,role="console",options="nowrap"]
.Sample Test method
----
 void testObjectNotDefined() {

	// tag::clibuilder_nullobject1[]
	CliBuilder clibuilder;

	// clibuilder should be null when not initialized
	assert clibuilder == null;

	// end::clibuilder_nullobject1[]

} // end of method
----

[source,role="console",options="nowrap"]
.Sample Result
----
	CliBuilder clibuilder;

	// clibuilder should be null when not initialized
	assert clibuilder == null;
----

TIP: The *assert* statement should have a remark before it. It should explain say why the test should succeed - *not* why it would fail icon:exclamation[]

'''

=== Add New Test Cases 

It's outside the scope of this document, though if you feel something is missing in our test coverage, please raise a question. Our mailing lists are an ideal place to ask questions and receive suggestions about how you can contribute new test cases. Everyone says more tests improve product quality. Can you think of any tests  we missed ?

==== Copyright Notice

It's always useful to identify the license terms for use with any asset you create or amend. A copyright statement does just that. Here's a sample copyright often used when doing test cases :

[source,role="console",options="nowrap"]
.Copyright 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.
 */
----


=== Forget Test Cases ?

Well, why not ? It's not critical to have samples of test stuff. Plenty of great documentation does not require any reference to tests or the content may not even be about code, logic, tests, scripts.
{'fraction_non_alphanumeric': 0.10979799886728336, 'fraction_numerical': 0.0056384116795670505, 'mean_word_length': 4.516628480177741, 'pattern_counts': {'":': 0, '<': 245, '<?xml version=': 0, '>': 179, 'https://': 66, 'lorem ipsum': 0, 'www.': 6, 'xml': 8}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2124087', 'n_tokens_mistral': 25854, 'n_tokens_neox': 24024, 'n_words': 8744}