Thank you for your interest in contributing to the ESMF SDK PY Aspect Model Loader. Use this repository to contribute to the SDK as easy and transparent as possible, whether it is:
- Reporting a bug
- Submitting a fix
- Proposing new features
- other
The ESMF SDK PY Aspect Model Loader is developed in the context of the Eclipse Semantic Modeling Framework (ESMF). More information about the ESMF is available under https://projects.eclipse.org/projects/dt.esmf. The overall goal of the ESMF is to work on a Semantic Data Structuring Layer that addresses the needs to share, join, and reuse heterogeneous data of the manufacturing. The ESMF SDK PY Aspect Model Loader is based on the Semantic Aspect Meta Model and supports its use.
- We use this GitHub repository to track issues and feature requests, as well as discuss and manage all PR's related to this project.
- Opening
Issues
andPRs
in GitHub is the preferred way to interact with the community around the ESMF SDK PY Aspect Model Loader.
Decisions on code and architecture are documented using Markdown Any Decision Records in documentation/decisions/.
We follow the Git branching guidance.
More specifically the repository has the following branches:
name of branch | description |
---|---|
main |
Contains the latest state of the repository |
v{version_number}-RC{rc_number} |
A state on which the working group agreed on as a release candidate but which is missing the approval by the OMP. |
v{version_number} |
A release of the respective version which is approved by the working group and the OMP. |
feature/#{issue_number}-{feature_name} |
Contains the development on a specific feature and is intended to be merged back into the main branch as soon as possible. Note, that it is recommended for contributors to create and develop feature branches in a personal fork and not the upstream repository. |
bug/#{issue_number}-{bug_name} |
Contains the development of (usually smaller) changes in files of the repository that do not introduce new functionality but fix mistakes, errors or inconsistencies. These branches should be merged back into the main branch as soon as possible. |
We use the Issues
feature of GitHub for tracking all types of work in the repository.
We distinguish between the following types of issues;
Issue Types | Description |
---|---|
Bug Report |
This Issue is dedicated to reporting a problem. |
Task |
This Issue is used for describing and proposing a new work item (e.g., a new feature) |
If there are issues that link to the same topic, the creator of the issue shall mention those other tasks in the description. To group tasks that can belong together, one could further create an issue mentioning and describing the overall user story for the referenced tasks.
Proposals for changes to the content of the repository are managed through Pull Requests (PRs
).
To open such a PR
, implement the changes in a new feature branch
. Each PR
must reference an issue and follows the
naming schema: <issue-number>-<feature-name>
. For a new PR
the target branch is the main
branch while the source
branch is your feature branch
The feature branch
branch should be developed in a fork of the upstream repository.
So before working on your first feature, you need to create such a fork (e.g., by pressing the Fork
button in the top
right corner of the GitHub page)
When opening a PR
please consider the following topics:
- optional: Rebase your development on the branch to which you plan to create the
PR
. - Each
PR
must be linked to anIssue
:- Reference the
Issue
number in the name of yourfeature branch
and the description of thePR
. - Mention the
Issue
in one of the commit messages associated to thePR
together with a GitHub keyword likecloses #IssueNumber
orfixes #IssuesNumber
. For more details visit the GitHub documentation on linking PR with Issues
- Reference the
- Each
PR
should only contain changes related to a single work item. If the changes cover more than one work item or feature, then create onePR
per work item. You may need to create new more specificIssues
to reference if you split up the work into multiplefeature branches
. - Commit changes often. A
PR
may contain one or more commits.
After new Issues
or PRs
are created, the bug
and task
label will be added automatically according to the chosen issue type.
Later on the Chair or one of the maintainers may further assign a label
to it according to this table:
Label Types | Description |
---|---|
to be discussed |
Involvement and Discussion in one of the working group meetings are needed. |
request for information |
The working group or the maintainers are requesting further information from the creator of the Issue or PR . If for a pre-defined time no information is received, then the Issue or PR can be closed. |
approved |
Has been discussed and approved in the working group . |
not accepted |
Has been discussed in the working group with the decision to close this issue. |
-
You can provide comments to any
PR
orIssue
via the comment function in GitHub -
If no further involvement from the working group is required, a
maintainer
may merge aPR
. This mostly applies to bug fixes and non-API-breaking changes. APR
for a bug fix has to reference an issue of typeBug Report
. -
The
maintainers
may assign the labelto be discussed
to a proposal when further involvement from theworking group
is required. This then triggers the following steps:- The
Chair
of theworking group
puts the proposal up for discussion in one of the nextworking group
meetings. - The
working group
then uses Consensus Decision-Making with one of the outcomes listed below. - The label
to be discussed
is removed.
Decision Next Steps Approved
The Issue
or thePR
gets the labelapproved
. In the case of aPR
, themaintainers
merge the respectivePR
.Discussion
The Issue
or thePR
get the labelrequest for information
.Close
The Issue
or thePR
are closed and get the labelnot accepted
. - The
-
If the
working group
or themaintainers
feel that further information is required to explain aPR
or anIssue
, they may request this information through the comment section of thePR
orIssue
and assign the labelrequest for information
. Themaintainers
may close the issue if no answer is received after a pre-defined time.
Note, that merging a PR
leads to the closing of the Issue
if it is linked in the PR
.
The following checklist can be seen as a basis for performing reviews on new PRs
:
- brief and useful commit messages
- code convention is followed
- the contribution matches to the linked issue and the description of the PR
- provide clear documentation of new features (if applicable)
- outline added third party dependencies
Separate the subject from the body with a blank line because the subject line is shown in the Git history and should summarize the commit body. Use the body to explain what and why with less focus on the details of the how. This blog post has more tips and details. Before you push your commits to a repository, you should squash your commits into one or more logical units of work, e.g., you should organize a new feature in a single commit.
All files contributed require headers - this will ensure the license and copyright clearing at the end. Also, all contributions must have the same license as the source. The header should follow the following template:
##
# Copyright (c) {YEAR} {NAME OF COMPANY X}
# Copyright (c) {YEAR} {NAME OF COMPANY Y}
#
# See the AUTHORS file(s) distributed with this work for additional
# information regarding authorship.
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
#
# SPDX-License-Identifier: MPL-2.0
##
When using the template, one must replace "{NAME OF COMPANY X}" with the name of the involved companies and "{YEAR}" with the year of the contribution. For each involved company you need a new line starting with "Copyright" as outlined in the example.
The example is taken from a Python class file. If your file is of another type you may have to adapt the comment syntax accordingly.
If you use third-party content (e.g., import / include ...), you are required to list each third-party content explicitly with its version number in the documentation and your pull-request comment. Please also check used third party material for license compatibility with the MPL-2.0. E.g. software licensed under GPL, AGPL or, a similar strong copy-left license cannot be approved.
The ESMF SDK PY Aspect Model Loader is written in the Python Programming Language. Please have a look into our Code Conventions.
The working group may decide that it reached a stable state for the contents of the repository. To settle an agreement on this and provide downstream users with a stable version of the ESMF SDK, a release process can be triggered.
For such a release the working group
must approve the current state of the main
branch as agreement.
A maintainer
of the repository then forks the main
branch into a new branch that follows the naming
convention v{version_number}-RC
. The organization team of the OMP is then asked to review & approve
the v{version_number}-RC
branch. If the organization agrees on the approval the OMP steering committee needs to be
notified. After that notification, a maintainer
triggers the release feature from GitHub based on the commit on
which the v{version_number}-RC
branch is based.
We use Semantic Versioning to identify released versions of the ESMF SDK PY Aspect Model Loader. Semantic Versioning is documented here. It proposes to have a versioning number with the following elements:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- PATCH version when you make backwards compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
Whereas the Major version must be incremented if the API has backward-incompatible changes (e.g., has breaking changes), the Minor version must be changed if new backward-compatible features are introduced and, the Patch version must be incremented if backward-compatible bugfixes are introduced.
For the definition of a breaking change, we follow the definition as in the Microsoft REST API Guidelines which are licensed under CC-BY-4.0. This definition states:
Changes to the contract of an API are considered a breaking change. Changes that impact the backwards compatibility
of an API are a breaking change.
Git version tag
vX.Y.Z-[pre-release-identifier]
Examples:
v1.0.0-RC1, v1.0.0