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.
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.
For devonfw we have the following organizations on GitHub:
The official devonfw Platform organization.
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.
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.
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.
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
There is much more to discover. Browse our organization to find out.
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
Previewtab at the top.
When your change is complete, select
Create a new branch for this commit and start a pull requestat the bottom.
Comit your change by clicking the green
Propose file changebutton at the bottom.
Now fill summary and description and click on the green
Create pull requestbutton.
That is all. Thank you very much! For details about pull requests read here.
For non-trivial changes please read on.
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.
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!
Before you start with your documentation changes, please check the following conventions:
Documentation will always be found in the
documentationfolder at the root of a repository.
All our documentation is written in the AsciiDoc format.
All documentation files need to carry the
.asciidocextension and should be named in
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.
To test your changes all you need to do is run the following command:
If the build failed, you need to rework your 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.
#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»
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.
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 Requestbutton 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 reviewbutton.
If you are providing a PR that is ready for merging, click on the green
Create Pull Requestbutton.
Your pull request will automatically be checked for these requirements:
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.|