How To Contribute

If you want to contribute to SilverWare, read this document in order to save both your time and the time of developers who maintain this project.

Repository

Before you start working on this project, you will need to set up your Git repository properly. To do so, follow these steps:

1. If you are not familiar with Git, read this book.
2. Set up your Git by following these instructions.
3. Fork SilverWare repository by following this guide.

Code style

In order to avoid unnecessary formatting commits, all developers are required to use the same code style. You can find code style configuration files for your IDE in code-formatting folder.

The source code is also checked by Maven Checkstyle Plugin. Try to fix all warnings from its report when making changes in this project. Besides other things, it also controls if you add JavaDoc to your code.

License

Add the following license header at the beginning of every Java file you add to SilverWare repository:

/*
 * -----------------------------------------------------------------------\
 * SilverWare
 *  
 * Copyright (C) 2017 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.
 * -----------------------------------------------------------------------/
 */

Build

SilverWare uses Apache Maven as a build tool. You will need to install Maven before you start working on this project.

To build this project, run the following command in SilverWare folder:

mvn clean install

It will check the source code, compile the project, and run the tests.

Testing

If you add new functionality to SilverWare, always write the tests for it. Add unit tests for all your components as well as integration tests which run SilverWare platform with your components.

Make sure all existing tests pass when you make any changes. Never submit a pull request with failing tests.

Pull requests

Contributions to this project are merged through pull requests. They help to avoid undesirable changes to be added to the project as well as allow developers to do code reviews. Always create a pull request, even if you have direct write access to the repository.

Workflow

Follow these steps to make your contribution as smooth as possible:

1. Update devel branch in your local repository with the latest changes from upstream:

   git checkout devel
   git pull upstream devel
   

2. Create a new feature branch where you will make your changes:

   git checkout -b my-branch-name
   

3. Make your changes in the project.

4. Commit your changed files.

5. Push the commit to your fork of SilverWare repository:

   git push -u origin my-branch-name
   

6. Go to SilverWare repository and GitHub will automatically offer you an option to create a pull request from your feature branch.

If you are requested to do some changes after the code review, follow these steps:

1. Amend your existing commit:

   git commit -a --amend
   

2. Push your commit to your fork:

   git push --force
   

Commits

Make sure you always add only a single commit per pull request. If you have made several commits during your development process, squash them into one before sending a pull request.

Write good commit messages. If you have not read How to Write a Git Commit Message, do it right now!