HowToParticipate

• Joining
• Contributing
  • Documentation
  • Code
    • VCS
    • IDE
    • Development
    • Definitions
    • Setting up your local repository
    • Updating from the main repository
    • Developing your code
    • Contributing to the main repository

Joining

We welcome new members to extJWNL project. If you want to fix a bug, update the documentation, implement or suggest a new feature - join the project.

There are many ways to contribute. Lets list few options, starting from simple and easy ones to better ones:

• think of a change, ask for a change.
• think of a change, change what you like, use it yourself.
• think of a change, change what you like, share with others. in whatever form you like, wherever you like.
• think of a change, change what you like, share with others. let us know, we try to integrate your changes.
• think of a change, ask us, change what you like, share with others through the project.

Below I describe the best way which will lead your changes into extJWNL.

extJWNL project is hosted on SourceForge, so create a SourceForge user account or login with OpenID. Then send a message with your SourceForge user id to Aliaksandr Autayeu telling why you would like to join the project and what you would like to contribute.

If you don't want to deal with SourceForge, it is enough that you clone the !Git repository and later on it will be easier to merge your changes into main extJWNL repositoty.

Contributing

Tell us you want to contribute and ask to join the project. We will help you to get started. We appreciate any help, especially programmers help and technical writers help.

Documentation

For Javadoc and code comments read Sun's How to Write Doc Comments for the Javadoc Tool and pick up bits of common sense in the following places:

• http://confluence.atlassian.com/display/CONF29/Javadoc+Standards
• http://www.edparrish.com/common/javadoc.html

Code

Read Sun's "Code Conventions for the Java Programming Language":

http://java.sun.com/docs/codeconv/

VCS

We use Git as our version control system. There is a good book on Git: Pro Git. Choose the version for your OS in the download section of Git site.

• Linux. Git is officially supported under Linux, use your preferred package manager to get it.
• Windows.
  • Git is available through Cygwin. Use Cygwin setup program to install:
  • git package from Devel category.
  • openssh package from Net category (if you want to set up key authentification to avoid typing password for each operation)
  • Git is also available through MSysGit project. With this option you have a GUI available, either the one from MSysGit or TortoiseGit.
• MacOS X. OSX Installer for Git

We recommend that those working under Windows configure Git to ignore file permissions by issuing the following configuration command in the repository:

git config core.filemode false

As a general recommendation we advise to make atomic well-commented commits:

• Atomic: Include in one commit all changes related to one logical change. For example, if you fix 2 bugs, include each one in a separate commit.
• Well-commented: For each commit write an explanatory message, which describes the changes you did at a high level, higher than 'diff' will show. For example, writing "refactoring" is too obscure, this will require looking in the diff; writing "changed variable a to b, supported interface c in class d and e" is better, but does not describe what is changed at a high level; while "improved standard collections framework support in D and E: changed variable a type to b, supported interface C in class D and E" is even better, because it contains high level change information (before :) as well as lower level details (after :).

IDE

There are plenty of good IDEs available, such as IDEA and Eclipse.

Development

We adopt the following development scheme. There is a master repository. In addition, each developer has own repository. The developer keeps own repository updated from the master repository. It might be useful to group development steps in features (or bug fixes) and organize those as branches. This will make the code review easier. When the developer is ready to contribute the code, the developer merges the latest code from the master into own repository, making sure the code merges smoothly and resolving conflicts as necessary. After all conflicts have been resolved, the developer commits and pushes the changes into the developer's own repository and signals Aliaksandr Autayeu to merge the new code into the master. I will review and merge the code and it will become public.

Now, step by step.

Definitions

Suppose jsmith is your login. Master extJWNL repository has the following address: ssh://jsmith@extjwnl.git.sourceforge.net/gitroot/extjwnl/extjwnl. It has main branch called master. We will create a repository for you. Your repository is called jsmith and has the following address: ssh://jsmith@extjwnl.git.sourceforge.net/gitroot/extjwnl/jsmith. In the beginning it also has only one branch, called master.

Setting up your local repository

To set up your local repository execute git clone ssh://jsmith@extjwnl.git.sourceforge.net/gitroot/extjwnl/jsmith. This will create a local copy of your own repository. This copy synchronizes with SourceForge servers using remote called origin.

Now add a reference to the master extjwnl repository: git remote add extjwnl ssh://jsmith@extjwnl.git.sourceforge.net/gitroot/extjwnl/extjwnl. Now your repository contains two remotes: origin, pointing to your own repository, and extjwnl, pointing to main extJWNL repository.

Updating from the main repository

Your repository has a reference to the main extJWNL repository, called extjwnl. Execute git fetch extjwnl to get changes from main extJWNL repository. Then execute git merge extjwnl/master to merge changes from master branch of the main extJWNL repository. After you merge successfully, resolving conflicts if they arise, build and test the code again. When you are sure it works, execute git push. Now your repository is ready for contribution to the main repository.

Developing your code

Develop your code in your preferred way, test it, commit it. The usual commands for that are: edit ..., git add -A, git commit -m "implemented foo.bar". See git help or man git for help on git. You may create your own branches and in general do whatever pleases you the most in your own repository. Write meaningful commit messages and from time to time update SourceForge servers by pushing your changes: git push. This will upload your commits to the SourceForge.

Contributing to the main repository

After you have done the steps above, write Aliaksandr Autayeu that your repository has a contribution ready to be merged, mentioning the branch where it is located. I will pull your changes into the main repository and make a release.