Groovy Contributions

Please join any of our mailing lists at 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 Groovy eco-system.

You can find live #groovylang feeds for up-to-the-minute news.

Open source developers often need somewhere to keep all their assets. These assets are typically stored in a repository somewhere on the internet. GitHub is one such storage facility. At Groovy, we keep our source code here.

Visit our Groovy information portal at

We build Groovy continuously at . Log in as a guest.

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. Follow this trail.

For larger contributions, it’s more likely you’ll need to copy Groovy into your own work environment, then Take The Long Way Home.

At Groovy, we keep our source code here.

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

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 Groovy.

So you can work on your own version of 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 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.

You now have your own version of 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.

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.

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.

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

Your sample log might look like this :

If your command log looks something like the above, then you have a valid Groovy installation, and you’ve also constructed a fresh local copy of the 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 :

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.

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 Groovy Documentation Tree. There are a large number of document files, one for each core component and each separate sub-project extension within Groovy. These are simple text file (no funny stuff) in a markup syntax called asciidoc. Document files end with .adoc.

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 Groovy code base - not your own GitHub version.

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:

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

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

So now you know how and where to look, you can review our 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.

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 Groovy admins to merge your amendment back into the 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.

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

A merge is known as a PULL request because you are asking Groovy admin to PULL your changes back into the Groovy codebase.

Click the PULL button to see the next panel.

Click the New Pull Request button.

You will need to enter a comment and title. It helps Groovy admin to understand what’s going on.

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

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 Groovy development environment. Of course, it’s an automatic feature of full Groovy build, but on a small scale, it’s much easier to see how things look when built locally before the full-build stage.

If you still wish to donate some expertise, but want to avoid a full 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 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 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.

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.

Given an asciidoctor declaration like this :

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

from this :

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

Ok, let’s review test cases next.

Review the 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.

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 ?

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.

An introduction describes the purpose of the document. Major topical areas are started by level one headings. More detailed text pieces would be started with level two headings.

Follow guidelines for version 1.4.0 of Asciidoctor.

As per our notes above about tags, write your document to include external text when appropriate.

Images of GUI panels improve understanding and act as a powerful aid to learn new and/or difficult concepts.

Groovy-core images and GUI related stuff can be put in the groovy-core/src/spec/assets/img folder. Sub-projects have their own image folders, so groovy-core/subprojects/groovy-servlet/src/spec/assets/img could keep images if a document concerns servlets.

Please try to keep the size of images small rather than use a very large image then ask asciidoctor to re-scale it smaller. This improves page load times for end users.

First, change directories to the groovy-core directory created in Copy Groovy step.

To rebuild your version of Groovy documents, try this. Run one of these commands depending on your operating system:

If your command worked ok, you’ll have a fresh local copy of the Groovy documentation.

You can check your local copy to see if it looks good. After a regen, there should be index.html page located in ./groovy-core/groovy-core/target/asciidoc/index.html ( your actual address may differ ).

Enter your own address in a browser to see this :

As you modify documents, you can now see how they look. Just navigate to the topic you’ve updated and enjoy the fruits of your efforts

git commit -am \'put a nice clear note here about what you did'

git checkout master

git merge <your branch name>

git push origin master

Follow the directions given in Stand And Declare to remove your id marker.

Again, do the same thing we did to create the request.

To follow the progress of your request, in a browser, enter https://github.com/apache/incubator-groovy to see the groovy-core home page in GitHub.

Look again. This is where you can saw how many other PULL requests were open, waiting to be done, including yours. Clicking Pull Request took you to the next page for that view.

is a continuous integration service. It’s the foundation of the service we use to build Groovy.

To see what’s going on, log in as a guest when you visit

PULL requests become merge requests upon acceptance. Each merge is given a task number, for this example our merge / PULL request 488 is assigned task number 2093. It was merged into the master core branch of Groovy. Click 488/merge to drill down into the details.

The next view has specific details about every build attempt made for this request..

Here we can see that our request 488 has been executed a number of times. Each time it received another task execution number. The most recent task was 2093 marked with Green mark. That means Success !

For even more detail, we can drill down again into task messages by clicking the request number. Click task Tests passed 17761 for next view.

Ok, so here is the good news ! Request was successful. It passed all 17,761 tests.

Oops There was an error !

As seen above in the task execution list, task 1968 had bad news. Clicking 1968 displays this view.

This needed some work on the part of the submitter to remedy the failure. The continuous integration server then scheduled and re-executed the revised submission.

When your request is merged into Groovy let everyone know