Skip to content

Latest commit

 

History

History
146 lines (97 loc) · 5.83 KB

CONTRIBUTING.md

File metadata and controls

146 lines (97 loc) · 5.83 KB
Raw

Contributing to uii-net-api

Code of Conduct

The uii-net-api project follows the Contributor Covenant Code of Conduct

Issues

How to Contribute in Issues

You can contribute:

  • By opening an issue for discussion: For example, if you found a bug, creating a bug report using the template is the way to report it.
  • By providing supporting details to an existing issue: For example, additional testcases.
  • By helping to resolve an issue: For example by opening a Pull Request

Asking for Help

Just open a regular issue and describe your problem.

Pull Requests

1. Fork

Fork the project on Github and clone your fork

$ git clone [email protected]:username/uii-net-api.git
$ cd uii-net-api
$ git remote add upstream https://github.com/virtomize/uii-net-api.git
$ git feth upstream

Also configure git to know who you are:

$ git config user.name "Jane Doe"
$ git config user.email "[email protected]"

2. Branch

Best practice is to organize your development environment by creating local branches to work within. These should also be created directly off the master branch.

$ git checkout -b example-branch -t upstream/master

3. Code

Add unit tests to test your code contributions.

For new features add a short description in the README.md.

4. Commit

It is a recommended best practice to keep your changes as logically grouped as possible within individual commits. There is no limit to the number of commits any single Pull Request may have, and many contributors find it easier to review changes that are split across multiple commits.

$ git add files/changed
$ git commit

Commit message guidelines

A good commit message should contain a short description what changed and why

  • The first line should contain a short description (not more than 72 characters)
    • e.g.: additional filter added to filter mails by whatever
  • if you fix open issues, add a reference to the issue
    • e.g.: issue-1337: fixed ...
  • if you commit a breaking change (see semantic versioning), the message should contain an explanation about the reason of the breaking change, what triggers the change and what the exact change is

5. Rebase

As a best practice, once you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.

$ git fetch upstream
$ git rebase upstream/master

This ensures that your working branch has the latest changes from master.

6. Push

If your commits are ready to go and passed all tests and linting, you can start creating a Pull Requests by pushing your work branch to your fork on GitHub.

$ git push origin example-branch

7. Open the Pull Request

From within GitHub, by opening a new Pull Request will present you with a template.

Please fill out all details, feel free to skip not necessary parts or if you're not sure what to fill in.

Once opened, the Pull Request is opened and will be reviewed.

8. Updates and discussion

While reviewing you will probably get some feedback or requests for changes to your Pull Request. This is normal and a necessary part of the process to evaluate the changes and there correctness.

To make changes to an existing Pull Request, make the changes to your local branch. Add a new commit including those changes and push them to your fork. The Pull Requests will automatically updated by GitHub.

$ git add files/changed
$ git commit
$ git push origin example-branch

Approval and Changes

Whenever a contributor reviews a Pull Request they may find specific details that they would like to see changed or fixed. These may be as simple as fixing a typo, or may involve substantive changes to the code you have written. While such requests are intended to be helpful, they may come across as abrupt or unhelpful, especially requests to change things that do not include concrete suggestions on how to change them.

Try not to be discouraged. If you feel that a particular review is unfair, say so, or contact one of the other contributors in the project and seek their input. Often such comments are the result of the reviewer having only taken a short amount of time to review and are not ill-intended. Such issues can often be resolved with a bit of patience. That said, reviewers should be expected to be helpful in their feedback, and feedback that is simply vague, dismissive and unhelpful is likely safe to ignore.

Reviewing

Reviews and feedback must be helpful, insightful, and geared towards improving the contribution as opposed to simply blocking it. If there are reasons why you feel the PR should not be accepted, explain what those are. Be open to having your mind changed. Be open to working with the contributor to make the Pull Request better.

Also follow the Code of Conduct

When reviewing a Pull Request, the primary goals are for the codebase to improve and for the person submitting the request to succeed. Even if a Pull Request is not accepted, the submitters should come away from the experience feeling like their effort was not wasted or unappreciated. Every Pull Request from a new contributor is an opportunity to grow the community.

Be aware that how you communicate requests and reviews in your feedback can have a significant impact on the success of the Pull Request.