Skip to content

Latest commit

 

History

History
126 lines (97 loc) · 6.69 KB

CONTRIBUTING.md

File metadata and controls

126 lines (97 loc) · 6.69 KB
Raw

Contribution Guideline ESMF Parent

Thank you for your interest in contributing to the ESMF Parent.

The ESMF Parent is developed in the context of the Eclipse Semantic Modeling Framework.

Contributing Source Code (using GitHub)

  • We use this GitHub repository to track issues and feature requests.
  • For general discussions of the ESMF, modeling questions etc. we use the community forum.
  • For discussions specific to development, the preferred way is the developer mailing list.

Branching

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 "release candidate": A version that freezes major features and
can be considered a pre-release of the next full release.
v{version_number} A full release of the respective version.
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 mainbranch as soon as possible.

Pull Requests

Proposals for changes to the content of the repository are managed through Pull Requests (PRs).

Opening Pull Requests

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 an Issue:
    • Reference the Issue number in the name of your feature branch and the description of the PR.
    • Mention the Issue in one of the commit messages associated to the PR together with a GitHub keyword like closes #IssueNumber or fixes #IssuesNumber. For more details visit the GitHub documentation on linking PR with Issues
  • 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 one PR per work item. You may need to create new more specific Issues to reference if you split up the work into multiple feature branches.
  • Commit changes often. A PR may contain one or more commits.

Eclipse Development Process

This Eclipse Foundation open project is governed by the Eclipse Foundation Development Process and operates under the terms of the Eclipse IP Policy.

Eclipse Contributor Agreement

In order to be able to contribute to Eclipse Foundation projects you must electronically sign the Eclipse Contributor Agreement (ECA).

The ECA provides the Eclipse Foundation with a permanent record that you agree that each of your contributions will comply with the commitments documented in the Developer Certificate of Origin (DCO). Having an ECA on file associated with the email address matching the "Author" field of your contribution's Git commits fulfills the DCO's requirement that you sign-off on your contributions.

For more information, please see the Eclipse Committer Handbook: https://www.eclipse.org/projects/handbook/#resources-commit

Commit Messages

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.

License Headers & Licensing

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 Java source 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.

Resources