Skip to content

Latest commit

 

History

History
354 lines (272 loc) · 14.1 KB

DEVELOPMENT.md

File metadata and controls

354 lines (272 loc) · 14.1 KB
Raw

Development process of the Accellera UVM implementation

An HTML-rendered copy of this document can be found at: https://github.com/accellera-official/uvm-core/blob/main/DEVELOPMENT.md.

In this document, the internal development process for Accellera's UVM Working Group is described. This document focuses on the technical aspects related to the development of the UVM-SV implementation. Legal and formal procedures are documented at http://accellera.org/about/policies.

Git pointers

Comprehensive documentation about Git, a distributed version control system, can be found in the Pro Git book, also available online. Since Git is 'distributed', it is a very natural choice for the distributed development process needed for the collaboratively evolving proof-of-concept implementation of UVM.

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

Repository Setup

The central source code repository of the Accellera UVM implementation is hosted in two sets of Git repositories at GitHub. The main repositories are private to the OSCI-WG organization and can be found at:

Members of the GitHub OSCI-WG organization with the necessary access rights can clone the private repositories via SSH from the locations

 git clone -o osci-wg git@github.com:OSCI-WG/uvm-core.git
 git clone -o osci-wg git@github.com:OSCI-WG/uvm-tests.git

respectively.

To obtain access to these repositories you need an account on GitHub. The OSCI-WG repositories are for Accellera members only. In order to see the private repositories, you will need to be added to the access list. To gain access, provide the account details to Accellera by sending your github username to mailto:uvm-chair@lists.accellera.org or mailto:lynn@accellera.org and your account will be enabled.

A read-only, public version of these repositories can be found at

The public repositories do not require membership in the OSCI-WG organization for access.

Relationship between private and public repositories

New features and enhancements are developed by the UVM WG in the private repositories, see below. Please check the CONTRIBUTING guidelines how to join Accellera and its working groups to contribute to the development of UVM.

The public repositories are typically updated only together with public releases of the Accellera UVM reference implementation.

In-between public releases, bug fixes may be published via the public repositories as well.

Creating a personal fork

In order to contribute changes to the different repositories, it is recommended to create personal (or company-based) [forks][10] of the repositories on GitHub and push the proposed changes (bugfixes, features, ...) there.

Note: Forks of the private repositories are only accessible to members of the OSCI-WG GitHub organization. Details of the intended work-flow are described in Basic branch setup.

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

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.

It is also good to create a few branches tracking the main OSCI-WG or accellera-official branches (The master branch has already been created).

(cd uvm-core && git checkout --track osci-wg/release)
(cd uvm-core && git checkout --track osci-wg/official)

The branch setup can be validated with the following commands and should indicate that the local master and release branches are tracking the upstream remotes.

~/tmp/uvmtest/uvm-core$ git branch -vv
  master  4cb3b20 [osci-wg/master] Merge pull request #39 from OSCI-WG/Mantis_5481
* release 4ed28a0 [osci-wg/release] added starting_phase update to the release notes
~/tmp/uvmtest/uvm-core$ cd ../uvm-tests/
~/tmp/uvmtest/uvm-tests$ git branch -vv
* master 8d95595 [osci-wg/master] Merge pull request #23 from ...
~/tmp/uvmtest/uvm-tests$

Since the OSCI-WG repositories and especially OSCI-WG/master and OSCI-WG/release branches are managed by Accellera you should consider them as 'read-only' i.e branches which receive your commits should have your own repositories as upstream repositories configured.

Note: OSCI-WG admins do have write access and CAN push directly to the repos. This capability should limited to repository maintenance only. To be on the safe side the branches official, release, and master should never receive local commits and they should never be pushed. [10]: https://help.github.com/articles/fork-a-repo

Git RCS Filters

The UVM distribution includes the RCS keywords, e.g. $keyword$ in the source files for the keywords File, Rev, and Hash.

Git does nothing with these keywords by default; however, the Git filter mechanism can be used to expand these keywords with useful information.

For example:

//----------------------------------------------------------------------
// Git details (see DEVELOPMENT.md):
//
// $File$
// $Rev$
// $Hash$
//
//----------------------------------------------------------------------

The details of how to enable such filters are beyond the scope of this document.

Development flow

Basic branch setup

The private uvm-core repository accessible via the OSCI-WG GitHub organization has three primary branches:

  • master

    The latest and greatest HEAD of the UVM development. This is, were all the new features and fixes go.

  • official

    The latest revision pushed to the public repository of UVM. This may also include changes that are not yet part of a release package.

  • release

    This branch is used to create the release tarballs, both internal and public snapshots. Since the uvm-tests repository is not released in a tarball it does not have a 'release' branch

The release branch is different from the master branch in that it fully tracks the contents of the released tarball. This requires the following changes compared to the master branch:

  • generated documentation added to content
  • internal files are stripped (.gitignore, internal documentation, ...).

To prepare a release, the master branch would then be merged into the release branch and the clean working tree could be used as baseline for the tarball (e.g., via git-archive(1)). Details are described in the release management document. The history of the (core library) repostitory could then look like shown in the following graph (time progresses upwards):

   time  feature   master  hotfix official
         branches    |          | |
    ^      |  |
    |                [master]
    |                |            [official]
    ^          ----- o            |
    |         /      |            o - [uvm-1.4.1]
    |        /    -- o           /|
    |       /    /   |          o |
    ^      |  o--   ...          \|
    |      o ...     |  --------- o - [uvm-1.4]
    |      |  o     .../          |
    |      o   \---- o -[release] ..
    ^       \       \|            |
    |        ------- o            o   (internal snapshot)
    |               ...           |
    ^                             o - [uvm-1.3]

It should usually be sufficient to keep the two branches master and official, and cherry-pick hotfixes for emergency releases directly on top of the official branch. For convenience, an additional release branch is used to mark the branching point for the last release to the public repositories.

If more sophisticated version branches are needed, a development model similar to the well-known "successful branching model" can be deployed. Not all aspects of this model are expected to be needed for the UVM implementation, as we usually maintain only a single (i.e., the latest) public release.

Adding a feature (set)

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 Accellera 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.

This sign-off procedure is required for contributions via the public repositories, and optional for contributions via the private repositories.

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 working group 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 LWG 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 working group's 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

Versioning scheme

In general, the versioning pattern for the UVM reference implementation follows a "Major Minor.Patch" scheme. The major version is the UVM version as defined in latest release IEEE Std. 1800.2, 2020 as of the writing of this document. The minor version is incremented for new Accellera releases with functional/additive enhancements. The patch version is incremented for bugfix/errata only releases.

Note The version number of the reference implementation is only incremented when official release tarballs are created. Patch updates published to the public repositories without an associated tarball shall not cause the version number to change.

Note In general, no compatibility guarantees are attached to these version numbers, not even for PoC implementation itself, to avoid burdens across different UVM implementations.