This document focuses on the technical aspects related to the development of the Functional Coverage for SystemC (FC4SC) library. Legal and formal procedures are documented at
http://accellera.org/about/policies-and-procedures
The central source code repository of the Functional Coverage for SystemC (FC4SC) library is hosted at GitHub. The read-only repository can be found at
https://github.com/accellera-official/fc4sc
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 Functional Coverage for SystemC (FC4SC) 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 (ororigin
). - 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.
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 master
branch:
git checkout -b <company>-<feature-xyz> master
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 master
branch may
receive other commits. In that case, consider rebasing the commits in
your feature branch onto the HEAD
of the master
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.
For Accellera members, the summary can be manually generated by
git request-pull master git@github.com/<account>/<repo>.git \
<company-feature-xyz>
to be sent to the Accellera Working Group email reflector.
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 master..<remote-name>/<company-feature-xyz>
git log <remote-name>/<company-feature-xyz>
After the contribution is accepted, it will be merged into the
master
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 master
. 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 master
branch into his feature
branch before carrying out the requested changes.
After the contribution has been fully merged into master
, 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
Vendors may be interested in maintaining their own, in-house flow to align the internal development of a derived implementation, while being able to pick fixes from other trees, and (hopefully) contributing fixes and features back to the reference implementation.
For this purpose members may employ the already mentioned "successful
branching model" by Vincent Driessen. The vendor can branch its
own development branch, e.g., develop-<vendor>
from the already
tracked working group development branch master
in his clone of the WG
repository. The vendor is then able to integrate commits on the WG
development branch by merging it into his his vendor development
branch.
Bug fixes to be contributed back to the WG consist usually of one or several isolated commits. They need to be cherry-picked from the vendor's development branch into a new branch created from the WG development branch:
git checkout -b <vendor>-fix-<bug> origin/master
git cherry-pick <commit>...
Once, the bug fix branch is ready, it should be pushed into the vendor's github account and a pull request created, as described in the feature branch section.
A new feature consists usually of a series of commits developed in a dedicated feature branched of the vendor's or WG's development branch. Only in the first case, a rebase on the top of the WG's development branch is necessary. To this end, branch first from the feature branch:
git checkout -b <vendor>-<new-feature> <private-feature-branch>
git rebase [-i|--interactive] --onto origin/master develop-<vendor>
Once, the bug fix branch is ready, it should be pushed into the vendor's github account and a pull request created, as described in the feature branch section.
Open issues (bugs, cleanups, features) 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.