Skip to content

Latest commit

 

History

History
179 lines (143 loc) · 11.1 KB

CONTRIBUTING.asciidoc

File metadata and controls

179 lines (143 loc) · 11.1 KB
Raw
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 as our social coding platform. Hence, we follow the principles of GitHub to deal with changes. If you are a first time contributor to GitHub projects, read first contributions

Additionally, if you stay active and continue contributing you should also learn about upstream merging and rebasing.

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.

Organizations

For devonfw we have the following organizations on GitHub:

  • devonfw

    The official devonfw Platform organization.

  • devonfw-sample

    The organization used for sample and demo repositories. Here you can find things working in action that can give you a jumpstart. We do not claim every sample to be up-to-date. However, it needs to build and run out-of-the-box without errors.

  • devonfw-training

    The organization used as a starting point for trainings about devonfw. We do not claim the repositories to be self-explanatory. In case you need to attend a training please contact us.

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

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.

For non-trivial changes please read on.

Issues

We are working issue-based, so check if there is already an issue in our tracker for the task you want to work on. 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 you are ready to go.

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!

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.

  • For automatic spellcheck we have integrated PySpelling in repositories. In case you have failure for spellcheck you can refer document here

  • Please read and follow our documentation guidelines.

contributing-internal-snippets

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.

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

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.

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.

ℹ️
 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.