88. 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.

88.1. Using GitHub

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

88.1.1. 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 you are ready to go.

88.1.2. 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.

88.1.3. Repositories

Within the organization 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 organization to find out.

88.1.4. 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.

  • Make the required changes.

  • When editing documentation, verify your change by switching to the Preview tab at the top.

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

  • Comit 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 read here.

88.1.5. 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.

88.1.6. 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).

88.1.7. Forking

The github.com platform supports a wonderful feature to fork a repository. Make use of this 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 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.

Sometimes, when working on your fork, there will be changes made to the original repository, which you might want to incorporate into your fork’s master branch. To do this, you can sync your fork:

  • Add the remote URL of the original repo to your list of remotes: git remote add upstream «remote-url»

  • Fetch the changes from the upstream remote: git fetch upstream

  • Check out your fork’s master branch: git checkout master (assuming you’re working on a feature branch)

  • Merge the changes from upstream/master into your fork’s master branch: git merge upstream/master

  • This brings your fork’s master branch into sync with the original repository without losing changes on your local feature branch.

  • Switch back to your feature branch to continue work: git checkout «feature-branch»

88.1.8. Code Changes

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

  • For each programming language we have a stack repository (see repositories) containing documentation about the coding conventions (example: Java). Please read and follow these conventions before making (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!

88.1.9. Documentation Changes

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

  • Documentation will always be found in the documentation folder at the root of a 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 but to still offer knowledge for people using that option, decision- is for rationales why a complex (technology) decision was made.

  • Please read and follow our documentation guidelines.

88.1.10. 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.

88.1.11. Committing Changes

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

#«issue-id»: «describe your change»
Then GitHub will automatically link the commit with 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

88.1.12. 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.

88.1.13. 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 missed out on something. However, you make your and our life easier, if you follow this Definition of Done (DoD) before providing your pull request.

88.1.14. Pull Requests

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

Please ensure the following aspects:

  • When selecting a title for your pull request, follow the same conventions that apply to commit messages.

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

  • If you are providing a PR that is not yet ready for merging, please use GitHub’s draft pull request feature:

    • Expand the drop-down menu of the green Create Pull Request button and select Create Draft Pull Request

    • You can make further code changes to your PR by pushing commits to the corresponding feature branch.

    • When you’re ready to get feedback on your PR, click the Ready for review button.

  • If you are providing a PR that is ready for merging, click on the green Create Pull Request button.

Your pull request will automatically be checked for these requirements:

  • 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 requests 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 merged, 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.
Last updated 2020-08-05 10:44:41 UTC