Skip to content

Latest commit

 

History

History
231 lines (169 loc) · 9.2 KB

CONTRIBUTING.md

File metadata and controls

231 lines (169 loc) · 9.2 KB
Raw

Execution Flow - Contributing Guide

Issues

  • If any problems or doubts occur while editing the project, create an issue describing the problem / doubt.

Pull Request - Guide

Branch

  • If the changes made do not change the structure of the application or the way to use any functionality, use the current branch; otherwise, creates a new branch in the following format:

If the current branch is N.x, the new branch should be called (N + 1).x (without parentheses), where N is a number

Attention: Do not make any changes using the master branch, as it will be the result of the merge with the latest version released.

Tag

  • Always create a tag before creating a pull request
  • Only create the tag at the end of your changes
  • only one tag per pull request must be created
  • Choose a different tag from the current tag. If the current tag is X.Y.Z, where X, Y and Z are numbers, create a new tag using the following criteria:
    • If the changes made are minor, that is, small modifications that do not change the way of using a feature or even for bug fixes, create the tag X.Y.(Z + 1) (without parentheses)
    • If new features are added, create the X.(Y + 1).0 tag (without parentheses)
    • If the way of using one or more features is changed, or even if a feature is deleted, create a new branch with the name (X + 1).x and create a new tag with the name (X + 1).0.0 (without parentheses)

Attention: Tag creation should be Annotated Tags type.

  • Released versions should be placed in the dist/X.Y directory, where X and Y are the released version numbers
  • Try whenever possible to add tests on each added feature. If a feature is edited, make sure the tests related to it continue to work.
  • Before adding a new functionality, it is recommended to create an issue describing the new functionality and a justification of why it would be useful to the application.

If the contribution is to correct a bug, the commit should be: bug fix # xyzw, where #xyzw is the issue id that quotes the bug. If not, the commit should be bug fix <DESCRIPTION>, where <DESCRIPTION> is a brief description of the bug that has been fixed.

Pull request submit

After making changes to the project, create a pull request with the project you have modified. Try to add a detailed description of what you changed from the original project. Avoid changing the structure of the project as much as possible to avoid breaking code.

Attention: Before making the pull request, make sure that:

  • Generate the version jar in the following format: executionflow-X.Y.Z.jar, where X, Y and Z are the numbers corresponding to the tag that will contain the changes made;
  • Update pom.xml with new version;
  • Document the changes according to the documentation standard mentioned above;
  • Create a new release with changelog.

Setting up development environment

In order to be able to execute any project file, it is necessary to import some dependencies to your IDE, among them:

Rodando o projeto no Eclipse

With Eclipse and dependencies installed, in order to run the project in the IDE, do the following:

  1. Import the project
  2. Probably several errors will appear. Ignore them. Left-click on the file pom.xml and select Run As -> Maven install

step1

  1. After installation is complete, left-click on the file pom.xml and select Maven -> Update Project...

step2

  1. Select the project, check the last 3 options and click on Ok

step3

Code style guide

The project uses the code style recommended by Oracle, with one exception: structures if-then-else, try-catch-finally and the like should not have a closed curly bracket (}) to the left of the keyword.

Example

Good

if (x == 2) {
	return "two";
}
else if (x == 3) {
	return "three"
}

Bad

if (x == 2) {
	return "two";
} else if (x == 3) {
	return "three"
}

Documentation standard

All classes, public methods and some variables use javadoc to explain its functionality.

Classes, inner classes and enumerations

Classes should use the following pattern:

/**
 * Class description.
 * 
 * @author		YourName < your_email@email.com >
 * @version		X.Y.Z
 * @since		A.B.C
 */

Where X, Y and Z are numbers relative to the version of the application in which the class was last modified and A, B and C identify the version of the application in which the class was created. The annotation is separated from the content with 2 tabs. In addition, internally, the class should be divided into sections, which are identified with the following pattern:

//-------------------------------------------------------------------------
//    [section_name]
//-------------------------------------------------------------------------

Where [section_name] can be:

  • Attributes
  • Constructor(s)
  • Methods
  • Getters
  • Getters & Setters
  • Setters
  • Initialization block
  • Tests
  • Test hooks
  • Serialization and deserialization methods
  • Enumerations
  • Inner classes

Methods

Public methods must be documented using javadoc.

Attention: Documentations using javadoc must have the tag name followed by two tabs followed by its value, with the exception of the @implSpec, @apiNote and @implNote tags, which contain only one tab. This is done in order to maintain uniform presentation of documentation

Jar generation

In order to generate the JAR file do the following:

  1. On the file pom.xml, update:
  • project.version
  • project.properties.version.major (if necessary)
  1. Generate JAR file
  • Console

mvn package

  • Eclipse
  1. Left-click on the file pom.xml and select pom.xml -> Run As -> Maven build...
  2. In the Goals field, type: package
  3. Click on Run
  4. Make sure that the JAR file has been generated in the directory dist/V.X/<FILENAME>, where V = project.properties.version.major and <FILENAME> is: executionflow-X.Y.Z.jar where X, Y, Z are the version numbers of the application corresponding to project.version.

Project structure

global-schema

/

Name Type Description
dist Directory Released versions
docs Directory Documentation files
examples Directory Examples of JUnit tests to see how the application works
lib Directory Libraries the project uses
src Directory Source files

/src

Name Type Description
assembly Directory Configuration files related to the generation of the JAR file
main Directory Application source files
test Directory Application test files

Appendix

Maven

See here how to install.

Creating branches

Create a new branch:

git checkout -b branch_name

Add to the remote repository:

git push -u origin branch_name

Example

git checkout -b v1.x
git push -u origin v1.x

See more here.

Creating tags

git tag -a tag_name -m description

Add to the remote repository:

git push -u origin tag_name

Example

git tag -a v1.0.1 -m "Performance improvement"
git push -u origin v1.0.1

See more here.