01. How to contribute

Pull requests

Pull request title

Clearly and concisely describes what it does
Refers to the issue that it solves, if available

Pull request description

Describes the main changes that come with the pull request
Any relevant additional information is provided

New Pattern

To work on a new pattern you need to do the following steps:

If there is no issue for the new pattern yet, raise new issue. Comment on the issue that you are working on it so that others don't start work on the same thing. You are encouraged to present your implementation idea so others can participate in the design phase and help.
Fork the repository.
Create a new folder for the pattern. The rough structure of the new folder would be as follows:
- etc (every resource related to the pattern, like diagrams)
- src (the source code of the pattern)
- README.md (the description of the pattern)
- pom.xml (the Maven project file)
Implement the code changes in your fork. Remember to add sufficient comments documenting the implementation. Reference the issue id e.g. #52 in your commit messages.
Format the code according to project Checkstyle configuration
- The build fails if the code is not properly formatted (see coding conventions)
- The build also fails if PMD static analysis finds violations
Create a simple class diagram from your example code using ObjectAid UML Explorer for Eclipse and put it inside the etc folder.
Add description of the pattern in pattern-README.md and link to the class diagram. (Attention, all internal links must be relative to the pattern subdirectory, otherwise the links don't link properly on the website)
Create a pull request.
Now that the pattern example is ready you should consider writing a blog post about it (see instructions below)
Please also consider creating a presentation about it (see instructions below)

Structure of the pattern-README.md file

--- # this is so called 'Yaml Front Matter', read up on it here: http://jekyllrb.com/docs/frontmatter/
layout: pattern # layout must allways be pattern
title: Best Pattern Ever # the properly formatted title
folder: best-pattern-ever # the folder name in which this pattern lies
permalink: /patterns/best-pattern-ever/ # the permalink to the pattern, to keep this uniform please stick to /patterns/FOLDER/
pumlid: SOME_HASH_HERE # the Plant UML webserver id, not yet mandatory but might be very useful, more on this in the 'Plant UML' section
pumlformat: svg # optional, if not used it defaults to 'png', but svg supports larger diagrams


# both categories and tags are Yaml Lists
# you can either just pick one or write a list with '-'s
# usable categories and tags are listed here: https://github.com/iluwatar/java-design-patterns/blob/gh-pages/_config.yml
categories: creational # categories of the pattern
tags: # tags of the pattern
 - best
 - ever
 - awesome
---

## Intent
Makes your code awesome

![alt text](./etc/best_pattern.png "Best Pattern Ever")

## Applicability
Use the Best Pattern Ever pattern when

* you want to be the best
* you need to ...

## Real world examples

* [Nowhere](http://no.where.com)

To add a new category or tag you need to edit the _data/categories.yml or _data/tags.yml file of the gh-pages branch. In there you should find a yaml list that can be extended.

Plant UML

Plant UML lets you quickly write all kinds of diagrams and is supported by our website. Class diagrams can be directly embedded via the 'pumlid' page variable. Other kinds of diagrams can use the jekyll include 'pumlImg.html':

{% include pumlImg.html id=page.pumlid format=page.pumlformat %}

JDP also uses an automatic generator of Plantuml diagrams from the java source code called URM.

To integrate a standard class diagram into your pattern submission follow these steps:

generate the diagram via mvn urm:map for simple one module patterns. Or for more complex multi module patterns look at how aggregator-microservices, naked-objects or api-gateway solved the problem or just ping markusmo3 for help
commit the generate puml file(s)
go to http://plantuml.com/plantuml/uml and add the following, while filling in the YOUR_PATTERN part. The url should point to your file in the 'raw' format.
```
@startuml
!includeurl https://raw.githubusercontent.com/iluwatar/java-design-patterns/master/YOUR_PATTERN/etc/YOUR_PATTERN.urm.puml
@enduml
```
submit the form, if successful the diagram should be displayed correctly, if not the error message should be display. Also review the diagram if everything is displayed correctly.

copy the id from the url

http://plantuml.com/plantuml/uml/HERE_IS_THE_PUML_ID

add the pumlid front matter variable with the in step 6. retrieved ID (example)

Note that Plantuml has little control over layouting, so it maybe shouldn't be used it the diagram is large and/or complex.

Plantuml diagrams are currently hidden on the main site until they are fully approved, but if you want to view them set up the gh-pages branch locally by following the 'Working with the web site' wiki page and decomment the reviewmode variable in '_config.yml' (by removing the hashtag before it) and serve locally.

Non-pattern Issue

To work on one of the non-pattern issues you need to do the following steps:

Check that the issue has help wanted badge
Comment on the issue that you are working on it
Fork the repository.
Implement the code changes in your fork. Remember to add sufficient comments documenting the implementation. Reference the issue id e.g. #52 in your commit messages.
Create a pull request.

For inspiration check out the following sources:

there is a good list of design patterns at Wikipedia
Martin Fowler's Catalog of Patterns of Enterprise Application Architecture
pattern language for microservices
Microsoft's Cloud Design Patterns

Links to patterns applied in real world applications are welcome. The links should be added to the corresponding section of the pattern-README.md.

Blog

To create a new blog entry you should follow the following steps:

Check that the topic you want to write about isnt allready covered by a previous blogpost
Fork the repository.
Create a markup file file in the /_posts/ folder of the gh-pages branch
Name it in the following convention: YEAR-MONTH-DAY-title.MARKUP
Where YEAR is a four-digit number, MONTH and DAY are both two-digit numbers, and MARKUP is the file extension representing the format used in the file. (Examples are below)
Write your blogpost (Structure is explained below)
Create a pull request.

Examples of valid post filenames:

2011-12-31-new-years-eve-is-awesome.md
2012-09-12-how-to-write-a-blog.textile

Structure of a blogpost:

--- # this is so called 'Yaml Front Matter', read up on it here: http://jekyllrb.com/docs/frontmatter/
layout: post # layout must allways be post
title: Best Pattern Ever # the properly formatted title
author: shortname # the authors shortname from the /_data/people.yml See older blogposts for reference
excerpt_separator: <!--more--> # optional, if you want to customize what is shown as an excerpt. Read up on it here: http://jekyllrb.com/docs/posts/#post-excerpts
---

Bla Bla Bla # the content of your blogpost

More info on writing a blogpost can be found on the official website

Presentation

To create a new presentation you should follow the following steps:

Read the remark.js instructions https://github.com/gnab/remark
As told in the Getting Started section create the presentation template in the pattern's etc folder with name presentation.html
Read through the other presentations already existing in the project (see https://github.com/iluwatar/java-design-patterns/issues/197)
Edit/test the presentation until you are happy with the result
Create a pull request