Skip to content

Latest commit

 

History

History
180 lines (140 loc) · 11.1 KB

CONTRIBUTING.asciidoc

File metadata and controls

180 lines (140 loc) · 11.1 KB
Table of Contents

Contributing

devonfw is truly free and open. We are looking forward to your contribution and are more than happy to receive your feedback and improvements to code and documentation. This page describes the few conventions to follow. Please note that this is an open and international project and all content has to be in English language. Also read our code of conduct.

Using github

We are using github.com as social coding platform. Hence, we follow the principles of github to deal with changes:

Account

In case you do not have an account please first join github. If you have a CORP username use it also as GitHub username. If possible and suitable also provide your real name in your profile. Now, that you are logged into github.com you are ready to go.

Organizations

For devonfw we have the following organizations on github:

  • devonfw

    The official devonfw Platform organization.

  • devonfw-forge

    The organization used for work on incubators and other research projects. New projects start here and in case they evolve properly and get mature, they are moved to the official devonfw organization.

Repositories

Within the organizations we have many different repositories. In case you want to give feedback or provide contributions you need to know the corresponding repository.

The major technology stacks have their own repository carrying the prefix devon4 followed by a shortcut for their stack or programming language:

Tools we provide typically have a repository named like the tool they provide (omitting prefixes like devon[fw]):

There is much more to discover. Browse our organizations to find out.

Trivial changes

Please note that for trivial changes like a typo in the documentation you do not need to follow a complex process. Please do the following:

  • Just browse to the file online on github

  • Click on the small pencil icon on the top right of the file content

  • Do the proposed changes

  • If available (when editing documentation) verify your change by switching to the Preview tab on the top.

  • When your change is complete, select Create a new branch for this commit and start a pull request at the bottom.

  • Comitt your change by clicking the green Propose file change button at the bottom.

  • Now fill summary and description and click on the green Create pull request button.

  • That is all. Thank you very much. For details about pull requests see below.

Issues

We are working issue-based so check if there is already an issue in our tracker for the task you want to work. Otherwise first create a new issue for it (e.g. a bug report or a feature request).

If you want to contribute actively to resolve the issue (by providing code, documentation, etc.), please assure via communication in that issue (comments, assigned user, etc.) that this is recognized and accepted by somebody from the community. Especially in case of more complex issues please get sure not to miss out such consensus with the community and ensure that there is a common understanding of what and potentially even how to do it. You surely do not want to invest your valuable work and time into something that will later be rejected by the community. When you have been assigned to the issue (see Assignees on the right) you are sure that nobody else will work on the same issue in parallel and ready to go.

Branches

Typically the latest development takes place on the develop branch. In case there is no such branch it will be the master branch. If you plan to contribute a bugfix, please check if there is a maintenance branch for the corresponding release (e.g. if you found a bug in version 3.4.5 and a branch develop-3.4.x exists this should be the baseline for your work).

Forking

The github.com platform supports a wonderful feature to fork a repository. Make use to create your private copy where you experiment and prepare your contribution in an isolated environment:

  • Visit the original repository you want to contribute to.

  • Click on the the Fork button at the top right. If asked for a destination choose your personal github account.

  • Clone this fork with a git-client to your local machine.

  • Checkout the branch to use as baseline (see above section)

  • From there create and checkout a new feature-branch (named feature/«issue-id»-«feature-keywords»)

  • Start your work on this new feature-branch.

Code Changes

Before you start with your code changes, please check the following conventions:

  • For each programming language we have a stack repository (see above) containing documentation about the coding conventions (example: Java). Please read and follow this conventions before doing (bigger) changes.

  • Use devon-ide to setup your development environment and get code formatters, etc. configured properly as we do not like "diff-wars" because of inconsistent formatter settings.

  • Thank you, happy coding!

Documentation Changes

Before you start with your documentation changes, please check the following conventions:

  • Documentation will always be found in the documentation folder of the root of repository.

  • All our documentation is written in the AsciiDoc format.

  • All documentation files need to carry the .asciidoc extension and should be named in lower-train-case style.

  • Common prefixes help to categorize documentation files: tutorial- is used for step-by-step instructions, guide- is used for guidelines on a particular aspect, coding- is for specific conventions or details about source-code, alternative- is for less official options that are not recommended as first class citizen but to still share knowledge for people using that option, decision- is for rationales why a complex (technology) descition was taken.

  • Please read and follow our documentation guidelines.

Testing changes

To test your changes all you need to do is run the following command:

devon build

If the build failed, you need to rework your changes.

Comitting Changes

Always commit your changes in small logical units associated with a issue (see above section) using the commit message format:

#«issue-id»: «describe your change»
Then github will automatically link the commit in the issue.

Example:

#1: added REST service for tablemanagement

In case you worked on an issue from a different repository (e.g. change in ide-settings due to issue in ide) we use this commit message format:

«organization»/«repository»#«issue-id»: «describe your change»

Example:

devonfw/devon4j#1: added REST service for tablemanagement

Pushing Changes

To make your changes public you need to push them. If you are doing this for the first time since you started your feature branch, you also need to publish that branch (git push -u origin feature/«issue-id»-«feature-keywords»). After that a git push is sufficient.

Definition of Done

To complete your changes ensure the following aspects:

  • You have tested your changes and the build succeeds

  • Code and documentation are in sync (if you coded new features you also extended documentation, etc.)

  • You followed the coding conventions and documentation guidelines

  • For new features you have added automated unit tests

Do not worry, we will assist you in case you are unsure or miss something out. However, you make your and our life easier, if you follow this Definition of Done (DoD) before providing your pull-request.

Pull-Request

Once you have completed your changes and DoD, you can finally create a pull-request (PR).

Please ensure the following aspects:

  • Follow the same conventions as for commit messages (see above) also for the title of the pull-request

  • In case you are providing a PR that is not yet ready for merging, please prefix the title with WIP:. This can be helpful to get feedback from travis or start early discussions on complex changes. Once you reached a state ready to be merged, simple edit the title and remove the WIP: prefix.

  • Also add the issue(s) to the description of the pull-request (e.g. fixes #«issue-id»).

  • Finally, click on the green Create Pull Request button.

Your pull request will automatically be checked if it …​

  • can be merged without conflicts

  • builds correctly (no compile or test errors)

  • CLA has been signed. If you contribute for the first time, you need to sign the CLA once.

Please ensure to do the required tasks and reworks unless all checks are satisfied. From here a reviewer should take over and give feedback. In the best case, your contribution gets merged and everything is completed. You might also get review feedback and are request for changes. In that case walk through the review feedback and try to resolve it. Once, you push your new commits, the PR gets updated automatically and all checks will verify again. Also github will automatically make resolved review comments as outdated. If you do not plan to put any further work into your PR before it is completed and merge, please let us know by writing an according comment. We might find resources to get the PR done for you if it is already valuable. In case you should not get feedback for weeks, do not hesitate to ask the community.

Note
 If one (typically the reviewer) has to change the base branch (because the wrong develop branch was used, see above) onto which the changes will be merged, one can do the same by following the instructions at here.