Skip to content

Latest commit

 

History

History
106 lines (80 loc) · 5.38 KB

CONTRIBUTING.md

File metadata and controls

106 lines (80 loc) · 5.38 KB
Raw

TaPaSCo Contributor's Guide

This guide assembles important information for people interested in contributing to TaPaSCo.

Intro

The code base of TaPaSCo consists of three main parts:

  • The tapasco tool for interfacing with HLS, composing designs and running design-space exploration. This part is written entirely in Scala.

  • The definitions of platforms, architectures, features and plugins. These are mostly written in TCL, a language understood by most EDA/CAD tools.

  • The TaPaSCo API and Linux kernel driver (TaPaSCo loadable kernel module, tlkm) for interfacing with accelerators from software. This part is written in C/C++.

We welcome contributions to all three parts. If you want to contribute to TaPaSCo, but do not know where to start, you can either have a look at issues on Github labeled with "good first issue" or contact us.

Coding Style

The (at least) four different languages currently used in the TaPaSCo code base of course require different coding styles and practices. Nevertheless, there is a number of general guidelines you should follow:

  • Use idiomatic code style: For each of the languages, there is a set of commonly accepted best practices, idioms and styling guidelines. Follow these practices.

  • Use meaningful names for functions, variables, classes, etc.: This should go without saying, however, we want to remind you to use meaningful names for the entities in your code.

  • Document your code: This should also be a given. Include comments in your code, in particular for complicated statements or parts difficult to understand.

  • Follow the given indentation scheme: You should use the same scheme for indentation as the existing code base, even if that does not match your personal preference. Please also make sure that your editor/IDE is not breaking things in the background.

  • Test your code: Make sure everything still works as expected, after you have introduced your change to the code. We do have CI in place, however we cannot test every usage scenario with that. Please try to make sure to test the functionality affected by your changes. For Scala, you can additionally provide tests, which will be run with the sbt test-command by CI.

  • Add copyright header: In case you create a new file, make sure to include the TaPaSCo copyright header.

Contribution Process

TaPaSCo uses the git-flow branching model for development. In short, this means that the develop-branch is the central branch for development. Features are developed on so-called feature branches, which are merged into develop when the feature is complete. For releases, a release-branch is forked from the develop branch and eventually merged into master to mark a release. Please make yourself familiar with the git-flow model before starting to develop.

The overall process for contributing to TaPaSCo looks as follows:

  1. Create a fork of TaPaSCo under your personal account or your organization. Simply use Github's fork-button for that.

  2. Create a feature-branch (or hotfix, whatever applies) from develop. We use the default naming convention of the git flow-extension, make sure to follow the same convention (feature branches are prefixed with "feature/"). Use a meaningful name for your feature branch.

  3. Commit your changes to the feature branch. During development, make sure to follow the coding style guidelines listed above. Also avoid unrelated changes, i.e. changes to parts of the code that have nothing to do with your feature, as these make it hard to review a contribution.

  4. After you have completed your feature, create a new pull request in the main TaPaSCo repository on Github. Make sure to setup develop as the target branch of your pull request. In the pull request, provide a short description of your feature that we can also use for release notes.

  5. The pull request feature of Github will show you whether your branch can be merged automatically (no conflicts) or needs manual merging. In the first case, we will use the automatic rebase and merge-feature to merge your feature after review. In the latter case, please manually integrate the changes that have happened on the develop-branch while you were developing your feature using git merge. If you need changes from new commits on develop during the development of your feature (e.g. hotfixes), please also use git merge to integrate them into your branch.

  6. Request a review by one of the TaPaSCo maintainers (jahofmann, cahz, sommerlukas). We will review your changes, giving you feedback on your code.

  7. When the review process is done, we will accept the pull request, merging your changes into develop. From this moment on, your feature will be part of TaPaSCo and you will have the honor of being a TaPaSCo contributor ;-) When the next release occurs on master, your feature will automatically be part of it.

If this process seems too complicated to you or you only have a small one-off change to make, you can also contact us with a patch.