10. devonfw Development

10.1. IDE Setup

This Tutorial explains how to setup the development environment to work on and contribute to devonfw4j with your Windows computer.

We are using a pre-configured devon-ide for development. To get started follow these steps:

  1. Get a Git client. For Windows use:

  2. Download the IDE

    • If you are a member of Capgemini: download devonfw ide package or the higher integrated devonfw distribution (for devonfw please find the setup guide within the devon-dist).

    • If you are not member of Capgemini: We cannot distribute the package. Please consult devon-ide to setup and configure the IDE manually. If you need help, please get in touch.

  3. Choose a project location for your project (e.g. C:\projects\devonfw, referred to with $projectLoc in this setup guides following steps). Avoid long paths and white spaces to prevent trouble. Extract the downloaded ZIP files via Extract Here (e.g. using 7-Zip). Do not use the Windows native ZIP tool to extract as this is not working properly on long paths and filenames.

  4. Run the script update-all-workspaces.bat in $projectLoc.

    update

    Hint: You can use update-all-workspaces.bat whenever you created a new folder in workspaces to separate different workspaces. This update will create new Eclipse start batches allowing to run a number of Eclipse instances using different workspaces in parallel.

    You should end up having a structure like this in $projectLoc

    folder structure
  5. Open console.bat and check out the git repositories you need to work on into workspaces\main. with the following commands:

    cd workspaces/main
    git clone --recursive https://github.com/devonfw/my-thai-star.git

    Do another check whether there are files in folder workspaces\main\my-thai-star\!

  6. Run the script eclipse-main.bat to start the Eclipse IDE.

  7. In Eclipse select File > Import > Maven > Existing Maven Projects and then choose the cloned projects from your workspace by clicking the Browse button and select the folder structure (workspaces\main\my-thai-star\java\MTSJ).

  8. Execute the application by starting the ´SpringBootApp´. Select the class and click the right mouse button. In the context menu select the entry Run as ⇒ Java Application (or Debug as …​). The application starts up and creates log entries in the Eclipse Console Tab.

    eclipse run as

    Once started, the backend part of the application runs on http://localhost:8081/mythaistar. This is protected by Spring Security, so an additional frontend needs to be started, that will be able to get the needed access tokens.

  9. Now switch within command line to workspaces\main\my-thai-star\angular and run yarn install followed by yarn start. Finally login with waiter/waiter at http://localhost:4200/restaurant/.

10.2. Issue creation and resolution

10.2.1. Issue creation

You can create an issue here. Please consider the following points:

  • If your issue is related to a specific building block (like e.g. devon4ng), open an issue on that specific issue tracker. If you’re unsure which building block is causing your problem open an issue on this repository.

  • Put a label on the issue to mark whether you suggest an enhancement, report an error or something else.

When reporting errors:

  • Include the version of devon4j you are using.

  • Include screenshots, stack traces.

  • Include the behavior you expected.

  • using a debugger you might be able to find the cause of the problem and you could be the one to contribute a bug-fix.

10.2.2. Preparation for issue resolution

Before you get started working on an issue, check out the following points:

  • try to complete all other issues you are working on before. Only postpone issues where you are stuck and consider giving them back in the queue (backlog).

  • check that no-one else is already assigned or working on the issue

  • read through the issue and check that you understand the task completely. Collect any remaining questions and clarify them with the one responsible for the topic.

  • ensure that you are aware on which branch the issue shall be fixed and start your work in the corresponding workspace.

  • if you are using git perform your changes on a feature branch.

10.2.3. Definition of Done

  • actual issue is implemented (bug fixed, new feature implemented, etc.)

  • new situation is covered by tests (according to test strategy of the project e.g. for bugs create a unit test first proving the bug and running red, then fix the bug and check that the test gets green, for new essential features create new tests, for GUI features do manual testing)

  • check the code-style with sonar-qube in eclipse. If there are anomalies in the new or modified code, please rework.

  • check out the latest code from the branch you are working on (svn update, git pull after git commit)

  • test that all builds and tests are working (mvn clean install)

  • commit your code (svn commit, git push) - for all your commits ensure you stick to the conventions for code contributions (see code contribution) and provide proper comments (see coding conventions).

  • if no milestone was assigned please assign suitable milestone

  • set the issue as done

10.3. Code contribution

We are looking forward to your contribution to devon4j. 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 (American) English language.

For contributions to the code please consider:

  • We are working issue-based so check if there is already an issue in our tracker for the task you want to work on or create a new issue for it.

  • In case of more complex issues please get involved with the community and ensure that there is a common understanding of what and how to do it. You do not want to invest into something that will later be rejected by the community.

  • Before you get started ensure that you comment the issue accordingly and you are the person assigned to the issue. If there is already someone else assigned get in contact with him if you still want to contribute to the same issue. You do not want to invest into something that is already done by someone else.

  • Create a fork of the repository on github to your private github space.

  • Clone this fork.

  • Before doing any change choose the branch you want to add your feature to. In most cases this will be the develop branch to add new features. However, if you want to fix a bug, check if an according maintenance branch develop-x.y already exists and switch to that one before.

  • Then the first step is to create a local feature branch (named by the feature you are planning so `feature/«issue-id»-«keyword») and checkout this branch.

  • Start your modifications.

  • Ensure to stick to our coding-conventions.

  • Check in features or fixes as individual commits associated with an issue using the commit message format:

    #<issueId>: <describe your change>

    Then github will automatically link the commit in the issue. In case you worked on an issue from a different repository (e.g. change in devon4j-sample due to issue in devon4j) we use this commit message format:

    devonfw/<repository>#<issueId>: <describe your change>

    So as an example:

    devonfw/devon4j#1: added REST service for tablemanagement
  • If you completed your feature (bug-fix, improvement, etc.) use a pull request to give it back to the community.

  • Your pull request will automatically be checked if it builds correctly (no compile or test errors), can be merged without conflicts, and CLA has been signed. 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.

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

  • see also the documentation guidelines.

10.4. devonfw Documentation

We are using the github AsciiDoc feature to create and maintain the documentation for devonfw. Also the documentation PDFs are generated from these AsciiDoc files.

The source of the documentation is always located in the documentation folder of the main git repository (see Code tab and then click on documentation). These files are automatically synchronized to the wiki. This is for pure usability reasons as people typically go to the Wiki tab on github repositories to look for documentation. However, the wiki is a read-only copy of the documentation folder from the Code repo.

10.4.1. Contribution to devon4j documentation

Contributions and improvements to the documentation are welcome. However, you should be aware of the following aspects:

  • Your contributions will become part of the devon4j documentation and is licensed under creative commons (see footer).

  • If you want to contribute larger changes (beyond fixing a typo or a link) please consider to get in contact with the community (by creating an issue) before getting started. You do not want to write complete chapters and then get your work rejected afterwards.

  • Please consult the DocGen manual as we are using DocGen to generate the documentation starting from devon4j-doc.

If you consider all the aspects above you can start editing the documentation if you have a github-account. For small and simple changes just go to the AsciiDoc file in the documentation folder. Then click on the pencil-icon (you have to be signed in). Now github will allow you to edit the raw AsciiDoc text. Do your changes and preview them (using the Preview tab). Once complete, commit the changes as a new branch. From there click on compare and pull-request and finally confirm your pull-request. For larger changes, you should create a fork just as for code-contributions. Often larger changes imply changes to documentation and code.

Last updated 2019-11-13 14:38:09 UTC