As an open-source standardization projects, we welcome and encourage the community to submit patches directly to the project. In our collaborative open source environment, standards and methods for submitting changes help reduce the chaos that can result from an active development community. This document explains how to participate in project conversations, log bugs and enhancement requests, and submit patches to the project so your patch will be accepted quickly in the codebase.
All intellectual property remains with the original contributors, and is subject to the original license terms described in the LICENSE file.
How to officially join ASAM or the project
Before you fill out the Membership Request Form we ask you to get familiar with the ASAM Statutes and the Regulation of Fees. If you have questions when determining your member class, please check the FAQs below or contact us at info@asam.net.
After turning in your Membership Request Form, the ASAM Office will forward your application to the Board of Directors for approval. Upon decision of acceptance, the ASAM Office welcomes you and guides you through the server registration process. We also provide all relevant information (e. g. guidelines) and answer any questions you may have. Our goal is to inspire you to become an active member of the community so you can take the full advantage of your membership.
See our Project Guide.
and also our Anti-Trust Reminder
Or contact our office: info@asam.net
This project uses the MPL-2.0 License (as found in the LICENSE file).
The license tells you what rights you have as a developer, provided by the copyright holder. It is important that the contributor fully understands the licensing rights and agrees to them. Sometimes the copyright holder isn’t the contributor, such as when the contributor is doing work on behalf of a company.
To make a good faith effort to ensure licensing criteria are met, this project requires the Developer Certificate of Origin (DCO) process to be followed. The DCO is an attestation attached to every contribution made by every developer. In the commit message of the contribution, (described more fully here), the developer simply adds a "Signed-off-by" statement and thereby agrees to the DCO. When a developer submits a patch, it is a commitment that the contributor has the right to submit the patch per the license. The DCO agreement is shown below and online at developercertificate.org.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as Indicated in the file; or
(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
The DCO requires a sign-off message in the following format to appear on each commit in the pull request:
Signed-off-by: Firstname Lastname <email@address.com> <comment>
The DCO text can either be manually added to your commit body, or you can add either -s or --signoff to your usual Git commit commands.
If you forget to add the sign-off you can also amend a previous commit with the sign-off by running git commit --amend -s.
You can add sign-offs to multiple commits (including commits originally authored by others, if you are authorized to do so) using git rebase --signoff.
If you’ve pushed your changes to GitHub already you’ll need to force push your branch after this with git push --force-with-lease.
If you want to be reminded to add the sign-off for commits in your repository, you can add the following commit-message git hook to your repository:
#!/bin/sh
#
# Check for DCO/Signed-off-by in message
#
if ! grep -q "^Signed-off-by: " "$1"
then
echo "Aborting commit: Commit message is not signed off" >&2
exit 1
fiPlacing this script into a file called .git/hooks/commit-msg and making it executable (e.g. using chmod a+x .git/hooks/commit-msg on unixoid operating systems) will prevent commits without a sign-off.
Feature additions and bug fixes from the community are very welcome. Therefore, feel free not only to report an issue but also to work on a solution right away. In order to implement changes, you can:
- fork the repository.
- request access to the contributors group. Then you can make your changes directly in this repository.
For both ways, the following workflow applies:
- Open an issue.
- Create a branch.
- Create a draft pull request.
- Convert the draft pull request into a 'real' pull request.
Labels are given for each step as described in the ASAM contribution workflow. The steps are further described in the following.
Before creating an issue, check if you are using the latest version of the project.
The first step is to identify and describe a bug or feature, or place a question. Open a new issue in the respective project GitHub repository with the respective template for a bug or a feature.
-
Do not open a duplicate issue! Search through existing issues to see if your issue has previously been reported. If your issue exists, comment with any additional information you have.
-
Prefer using reactions, not comments, if you simply want to "+1" an existing issue.
-
Fully complete the provided issue template. The templates requests all the information we need to quickly and efficiently address your issue. Be clear, concise, and descriptive. Provide as much information as you can.
-
Use GitHub-flavored Markdown. Especially put code blocks and console outputs in backticks (`). This improves readability.
-
Use Labels to categorize the issues. Please check the official ASAM issue guideline.
In short, provide a ticket that you would like to receive.
Create a new branch where you can start working on the issue. You can use the link on the right side in the issue ("Development: Create a branch for this issue") to automatically create a new branch for the issue.
In order to create a branch, either fork the repository or request access to the contributors group.
Before forking the repo and creating a pull request for non-trivial changes, it is usually best to first open an issue to discuss the changes, or discuss your intended approach for solving the problem in the comments for an existing issue.
Note: All contributions will be licensed under the project's license.
-
Smaller is better. Submit one pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. Do not refactor or reformat code that is unrelated to your change. It is better to submit many small pull requests rather than a single large one.
-
Coordinate bigger changes. For large and non-trivial changes, open an issue to discuss a strategy with the maintainers.
-
Follow existing coding style and conventions. Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes it easier to review and modify in the future.
-
When writing comments, use properly constructed sentences, including punctuation.
-
Use spaces, not tabs.
-
After creating the branch, commit your first changes. Follow the signing instructions for commits (DCO) above).
-
Create a draft pull request and fill it out accordingly. Be sure to link the issue you created earlier in the pull request.
-
In the bottom, you can select to either submit as a pull request or as a draft pull request.
-
Use a draft pull request first, so the community can already see the ongoing work.
-
In this stage, the review from the project group and the service provider takes place.
Also, the CI pipeline will run for every commit, so you can continuously check your work.
Once you are done with your changes and all reviews took place, convert the draft to a pull request.
By this, the change control board (CCB) knows that you are done with your work and that the pull request is ready for review and merge.
The CCB is a subgroup of experts from the project and responsible for internal alignment of topics, release management and approval/review of pull requests:
- Issue and MR/PR review
- Classification of issues
- Assignment of issues to solution developer(s)
- Milestone monitoring and planning
- Ensure alignment of individual Subgroup topics
- Release management
Please write a great commit message.
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line (example: "Fix networking issue")
- Wrap the body at about 72 characters
[TAG] Short summary of changes in 50 chars or less
Add a more detailed explanation here, if necessary. Possibly give
some background about the issue, etc. The body of the
commit message can be several paragraphs. Further paragraphs come
after blank lines and please do proper word-wrap.
Wrap it to about 72 characters or so. In some contexts,
the first line is treated as the subject of the commit and the
rest of the text as the body. The blank line separating the summary
from the body is critical (unless you omit the body entirely);
various tools like `log`, `shortlog` and `rebase` can get confused
if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how or what. The code explains
how or what. Reviewers and your future self can read the patch,
but might not understand why a particular solution was implemented.
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
- Bullet points are okay, too
- A hyphen or asterisk should be used for the bullet, preceded
by a single space, with blank lines in between
Note the fixed or relevant GitHub issues at the end:
Resolves: #123
See also: #456, #789