Skip to content

Onboarding MAP Lib Project Leader and Deputy

Jump to bottom
Thomas Beutlich edited this page Jan 28, 2023 · 18 revisions

Welcome

Welcome to MAP-Lib - the people who are involved with the development and maintenance of the Modelica Standard Library (MSL)!

To give you a smooth start as Project Leader or Deputy we created this bullet list with the important topics, concepts and workflows. You simply can check (in Wiki editing mode) the individual items while you are on it.

Formal things first

  • Make sure you are an individual MA member, see the project rules
  • Make sure you signed the MA CLA
  • Make sure you become a MAP-Lib member
  • Create a GitHub account and tell the MA webmaster to add you to the Modelica organization at GitHub and give you the necessary rights and roles
  • Update annex 4 of the project rules

General onboarding topics on software development

Git

  • Understand the purpose of Git as a version control system
  • Learn the basic Git workflow: branching, committing, pushing, merging
  • Follow best practices for committing: clear and descriptive commit messages, frequent small changes
  • Use branches for managing different versions of code
  • Push changes to a remote repository and pull changes from others
  • Learn to resolve merge conflicts
  • Learn about different merge strategies: rebasing, squashing, merge-commits
  • Learn how to cherry-pick commits, and the use cases for it.
  • Learn how to use git log, git diff and git stash
  • Utilize resources for further learning and practice: tutorials, cheat sheets, documentation
  • Understand the concept of git tag and how to create and manage tags
  • Get familiar with the Git client of your choice, see for example GUI clients for git on Windows
  • Feel free to update References, how-tos and tutorials to Git

GitHub

  • Understand the purpose and features of GitHub as a collaboration platform
  • Learn how to navigate the GitHub interface and find information
  • Understand the concept of GitHub issues and how to use them for tracking bugs, feature requests, and project management
  • Understand the concept of pull requests and how to use them for code review and collaboration
  • Understand the concept of GitHub discussions
  • Learn how labels of GitHub issues and pull requests are used for categorization
  • Learn how GitHub milestones can be used for defining and scheduling development targets
  • Learn how to merge pull requests and resolve conflicts
  • Understand the concept of GitHub releases and how to use them for software distribution
  • Learn how to fork a repository and how to submit pull request to a repository you don't own

Continuous Integration (CI) with GitHub Actions

  • Understand the purpose and benefits of Continuous Integration (CI)
  • Learn about GitHub Actions and its integration with GitHub
  • Learn how to set up and configure GitHub Actions workflows for your projects
  • Learn how to use GitHub Actions to run tests and build your project
  • Learn how to use GitHub Actions to deploy and release your software
  • Learn how to use GitHub Actions to automate other tasks such as linting, code formatting, and dependency management
  • Understand the importance of using GitHub Actions to ensure code quality and reduce integration problems
  • Learn how to troubleshoot and debug GitHub Actions workflows

Semantic Versioning (Semver)

  • Understand the purpose and benefits of semantic versioning
  • Learn about the basic structure of a semantic version number (MAJOR.MINOR.PATCH)
  • Learn the rules for incrementing the MAJOR, MINOR and PATCH version numbers
  • Learn how to communicate and document breaking changes, new features and bug fixes using semantic versioning ((e.g., breaking changes increment MAJOR, new features increment MINOR, and bug fixes increment PATCH))
  • Understand the importance of maintaining backwards compatibility
  • Learn how to use version numbers in software development and distribution
  • Understand the importance of clear and detailed release notes when updating software versions

MAP-Lib specific onboarding topics

Organizational

MSL generally

  • Understand the purpose and features of the Modelica Standard Library (MSL)
  • Learn how to navigate and find information within the MSL documentation, for example by checking the online documentation
  • Learn about the organization and structure of the MSL
  • Learn about the various sub-libraries included in the MSL, such as the Modelica.Electrical, Modelica.Fluid, and the Modelica.Mechanics libraries
  • Learn how to validate and verify the models created using the MSL
  • Get familiar with ModelicaTest, where the unit and some integration test models for the MSL are developed
  • Get familiar with ModelicaReference, the reference documentation for the Modelica Language Specification (MLS)
  • Understand the development and contribution workflow

MSL GitHub issues and pull requests

Several workflows have been established for working with GitHub MSL.

  • The summary of issues and pull requests is relevant. Since this summary is the input for the auto-generated release notes it should be representative from a user's perspective. Here's how it looked for latest MSL v4.0.0: Auto-generated release notes for resolved GitHub issues and pull requests
  • Labels are used to categorize the issues and pull requests. You can check the label comments how they are meant to be used: Some examples:
    • The bug label especially also means, that this pull request shall be back-ported (using git cherry-picking if possible) to other active maintenance branches
    • A priority labels P: prio usually has no further effect.
    • A library label P: library categorizes the relevant libraries the issue relates to. If no library label is set, the MSL generally is affected by the corresponding issue or pull request.
    • enhancement is meant to be a new feature
    • documentation is to be set if only the Documentation annotation or a DocumentationClass is affected, for example for updating the user guides
    • invalid, duplicate or wontfix are set for closed issues and pull requests that did not contribute to the development
  • Milestones are used to target the developments
    • MSL5.0.0 is the next major (i.e. backward incompatible) MSL release - to be branched/tagged from master branch
    • MSL4.1.0 is the next minor MSL release - also to be branched/tagged from master branch
    • MSL4.0.1 is the next patch MSL v4 release - to be branched/tagged from the maint/4.0.x branch
    • MSL3.2.3+maint is the next patch MSL v3.2.3 release - to be tagged from the maint/3.2.3 branch
    • maintenance is used for all other tasks, e.g., when updating administrative files like the .gitignore file
    • never is a dummy milestone for closed issues that were closed as invalid, duplicate or wontfix.
  • The assignees (for issues) and reviewers (for pull requests) are to be set following the library officers mentioned in annex 3 of the project rules.
  • Ideally, library officers would check reviews within two weeks, but this rarely is the case.
  • Two review approvals, no unresolved conversations and a passing CI are required for merging a pull request.

MSL development

  • Obviously, there is a development conflict here, if both MSL4.1.0 and MSL5.0.0 are developed at the same branch: master.
    • Until now we got around this development conflict by not merging any backward incompatible commits.
    • Hopefully, the master branch (as of commit 89d5175) is still backward compatible to MSL v4.0.0, such that a potential new MSL release is a minor release, and not a major release.
    • You can convince yourself: So far there are no closed issues targeting milestone MSL5.0.0.
    • There have been discussions about the definition of backward incompatible changes. This discussion did not result in any written consensus, but - on purpose - we did not merge any changes to master that either require library conversion scripts or new MLS features.
    • For that reason the master branch ((as of commit 89d5175)) ist still with MLS 3.4 (and pull requests requiring newer MLS features such as #3686 or #3700 are blocked.
    • Ideally, the next MSL release would be a minor release v4.1.0 branched from master branch - still following MLS 3.4.
    • Ideally, the bug-fixes of v4.1.0 are also release as a new patch release v4.0.1.
  • For bug-fixes we usually insisted on a test model (for ModelicaTest) reproducing the bug (w/o the patch applied) and demonstrating the fix if the patch is applied.
  • For new library components we usually insisted on new example models demonstrating the use of the new component.
  • Both new test and example models require the definition of a comparisonSignals.txt file in ModelicaTest/Resources/Reference or Modelica/Resources/Reference, respectively. There is no automatic CI check here, unfortunately, as our previous attempts all failed.
  • Usually the revision annotation of changed components is not maintained, but that is up to the library officer. See also #3769

MSL release

  • Release creation should follow the recommended release schedule in annex 7 of the project rules
  • There are two options how and where to tag the alpha, beta, release candidate and final releases.
    1. Freeze the current development branch and create tags at the current development branch
      • Advantage: No potential back-porting necessary
      • Disadvantage: No parallel development possible
    2. Branch of a new branch, say maint/4.1.x from master for MSL v4.1.0, v4.1.1 etc releases, and create tags at the new maint branch.
      • Advantage: Parallel development is still possible
      • Disadvantage: Any new fixes found later during testing etc. need to be back-ported to the main development branch
    • So far, we went for option 1, but option 2 seems the cleaner approach.
  • The release checks and release workflow is already documented in the Wiki
  • The auto-generated release notes of resolved GitHub issues can be created by script Generate-ReleaseNotes.py or the corresponding GitHub Action. Unfortunately, it is broken, with a quick-fix available by #3999. There might be more sustainable solutions using custom Docker containers in the future.
  • Library comparison (see for example MSL v4.0.0 vs. MSL 3.2.3) is run in Dymola
  • The manually edited release notes require careful editing and selecting the relevant changes. See MSL v4.0.0 for an example how to edit the corresponding table
    • Table of new libraries
    • Table of new components in exiting libraries
    • Table of updated components (in a backward compatible way)
    • Table of updated component (in a backward incompatible way, only for major releases)
    • Table of critical bug-fixes, i.e., errors that could lead to wrong simulation results
  • Of course, the auto-generated release notes of resolved GitHub issues and the library comparison table (created in Dymola) can be used to edit these tables.

MSL regression testing

Clone this wiki locally