First contribution

This page aims at helping you to get started with AixLib by making your first contribution to the library. This is especially aimed at new students and researchers at EBC who have not yet made any contributions to AixLib. We think it is a good idea to familiarize yourself with the library and our workflows before starting your own development. You can do that by working on a very small and easy-to-solve problem. At the end of this process, you will have made a meaningful contribution to AixLib and know our collaboration workflow first hand. This will greatly help you in your own developments and save you a lot of time and trouble when you want to add your own models to AixLib.

Get ready to work with AixLib

In order to work with AixLib, you should have a basic understanding of Git and how to use it. Please refer to our Git-Tutorial for more information on how to get started with this version control system.

If you need to get started with Modelica, we recommend you to work through Michael Tiller's free online book Modelica by Example before working with AixLib.

Also, please read this Wiki before you start, especially our Modelica Guidelines. Don't worry if not everything makes sense to you on your first read, it already helps to have an overview of what the Wiki contains for future reference.

In addition, make sure you have the latest version of Dymola on your machine and clone the AixLib repository to your local file system. As you will contribute to the current development of AixLib, switch from the master branch to the development branch in your local AixLib repository. Now you are ready to start.

Choose a good first issue

You can find all currently open issues with AixLib in our Issue Tracker. Some of these issues require larger efforts, while some are very easy to solve and well suited for beginners. We marked these easy-to-solve issues with the label good first issue. You can filter for these issues by typing is:issue is:open label:"good first issue" into the filter bar on the Issue Tracker.

If there is at least one open issue labeled as a good first issue, you can chose any of these issues to work on. If there are 0 good first issues, you can create a new issue simply stating that "there are no open good first issues" and that you would like to work on one. We will then quickly help you to find a suitable issue.

Once you have found a good first issue that noone is working on yet, you can use the issue's conversation to post that you will start to work on this issue. If you are a member of EBC, you can assign the issue to yourself. If you have any questions, just post them to the issue and we will help you along. Don't worry or hesitate to ask for help!

Solve your chosen issue

Once you have informed everyone that you are working on the issue and clarified all your open questions via the Issue Tracker, you can actually work on the issue. To do this, you should create a new branch on your local AixLib repository named issueX_Y where X is the issue number and Y is 1-2 words describing your issue. See the overview of our branches for examples of how we name them. Make sure your branch starts off the most recent version of the development branch (i.e. your local repository currently has the latest version of the development branch checked out when you create the branch).

Now you can open AixLib with your new branch active in Dymola and work on the issue. Make sure to stick to our Modelica Guidelines. If you have any questions or problems while working on the issue, just use the issues conversation on the Issue Tracker to ask for clarification or for help.

While working on your branch, make sure to commit every step to your local repository, using good commit messages and referencing the issue (by including the issue number with the hash sign in your commit message, e.g. #372). If you push your branch with these commits to the AixLib repository on GitHub, these commits will automatically appear on the issue's conversation. Thus, everyone can follow your developments and help you along the way.

To receive the credit you deserve for all your efforts, please also do not forget to add your author information to the model's revision history as described here.

Create a pull request

Once you think you solved the issue in your local branch, you can create a pull request. Before you do so, make sure to pull the latest version of the development branch to your local branch (i.e. your local repository should be in the local branch you worked on while you pull the latest version of the development branch from the repository on GitHub, e.g. by running pull origin development from the command line). Now push your branch to the AixLib repository on GitHub again. After that, you can go to the pull requests page to open a new pull request. This means that you suggest to merge your work into AixLibs main line of development. To do that, please make sure you choose the development branch as your base branch for the pull request, not the master branch. This is because we collect new features in the development branch before making releases to the master branch.

We will assign someone to review your code before we merge it. Please collaborate with your reviewer to fix any open points that come up during the review. Once the review is over, we will merge your work and you have become an active contributor to AixLib! Thank you for your contribution!

Continue with your own development

Now that you have experienced our workflow first hand, you should have all the knowledge to actively collaborate on the further development of AixLib. You can now start your own issues, discuss changes with our community and contribute fixes and new models. Welcome as an active AixLib contributor!