83. Using GitHub
We are using GitHub as our social coding platform. Hence, we follow the principles of GitHub to deal with changes:
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:
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.
83.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
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.
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.
Typically the latest development takes place on the
In case there is no such branch it will be the
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).
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
Forkbutton 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
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»
83.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!
83.9. Documentation Changes
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.
Please read and follow our documentation guidelines.
83.10. Testing Changes
To test your changes all you need to do is run the following command:
If the build failed, you need to rework your changes.
83.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.
#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
83.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.
83.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.
83.14. Pull Requests
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.|