Skip to content

Files

Latest commit

barnascbarnasc
add contributing and development documents
Sep 20, 2022
e72d3d0 · Sep 20, 2022

History

History
150 lines (112 loc) · 6.26 KB

DEVELOPMENT.md

File metadata and controls

150 lines (112 loc) · 6.26 KB

Development process of the Accellera SystemC Common Practices library

This document focuses on the technical aspects related to the development of the SystemC Common Practices library. Legal and formal procedures are documented at

https://accellera.org/about/policies-and-procedures.

Repository setup

The central source code repository of the Accellera Common Practices library is hosted at GitHub. The read-only repository can be found at

Creating a personal fork

In order to contribute changes to the repository, it is recommended to create personal (or company-based) forks of the repository on GitHub and push the proposed changes (bugfixes, features, ...) there. Details of the intended work-flow are described in the next section. It is convenient to add this GitHub fork as a remote to your local clone of the repository:

  cd <repo>/
  git remote add origin git@github.com:<your-account>/<repo>.git
  git branch --set-upstream master origin/master

Contributions to the Accellera SystemC Common Practices library should comply with the contributing guidelines.

Any changes can then be pushed to GitHub using:

  git push [options] [<repository>] [<refspec>...]
  • If you omit the <repository>, the default destination is the remote of the current branch (or origin).
  • The <refspec> basically follows the format <local-branch>:<remote-branch>, or just <branch>, if both are the same.
  • Omitting the <refspec> pushes all branches with 'matching' remote branches to the repository.

A basic cheat sheet containing the an overview of the general Git commands and workflow can be found online.

Development flow

Adding a feature (set) or bug fix

The development of a new contribution in form of a feature or a complex bug fix is best done in a new feature branch, which is forked and checked out from the main branch:

  git checkout -b <company>-<feature-xyz> main

Then code up the new contribution. Please try to facilitate code review by other Accellera members by logically grouping your changes into one commit per addressed issue. For the commit messages, please consider to follow these suggestions:

Note: Commit messages

Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. Tools that turn commits into email, for example, use the first line on the Subject: line and the rest of the commit in the body.

Note: Sign-off procedure for commits

In order to document that contributions are submitted under the Apache-2.0 license (see LICENSE), a sign-off procedure is defined in the contributing guidelines.

During the development of the contribution, the main branch may receive other commits. In that case, consider rebasing the commits in your feature branch onto the HEAD of the main branch to keep the history clean. Once the contribution is ready for review by the working group, push the feature branch in your fork of the respective repository on GitHub:

  git push <your-github-fork-remote-name> <company>-<feature-xyz>

Then, send a pull request either manually or via GitHub to initiate the code review by the Accellera working group members.
The summary can be manually generated by

  git request-pull main git@github.com/<account>/<repo>.git \
          <company-feature-xyz>

To review the proposed contributions, one can either browse the repository at GitHub, or add the remote location to a local clone of the repository

  # add the fork to your set of "remotes"
  git remote add <remote-name> git@github.com/<account>/<repo>.git
  git fetch  <remote-name>

  # examine differences
  git diff main..<remote-name>/<company-feature-xyz>
  git log <remote-name>/<company-feature-xyz>

After the contribution is accepted, it will be merged into the main branch by the responsible source code maintainer. This should be done with an explicit merge commit, to keep the individual contributions separated:

  git merge --no-ff --log \
     <remote-name>/<company-feature-xyz>

Instead of fully merging the contribution, the maintainer may choose to cherry-pick individual commits or to rebase the feature branch on an intermittently updated main. He may also request additional changes to be done by the submitter. In that case, the submitter may need to merge recent changes to the main branch into his feature branch before carrying out the requested changes.

After the contribution has been fully merged into the main branch, the feature branch in the local and Github fork may be deleted.

  git branch -d <company-feature-xyz>      # delete local branch
  git push  origin :<company-feature-xyz>  # delete remote branch

Issue tracking

Open issues (bugs, cleanups, features) related to the reference implementation of SystemC Common Practices library are tracked via GitHub:

The discussion on issues usually starts on the Accellera Working Group email reflector or during the working group meetings. After an initial consensus on the "validity" of the issue, the issue is added to the issue tracking system, a classification is done (including a target milestone), and preferably a responsible person is assigned.