Contributing to intel-cmt-cat

=============================

As an open source project, we welcome contributions of any kind.

These can range from bug reports, code reviews and code development,

to significant code or documentation features.

How can I contribute?

=====================

This document specifies contributing guidelines to the intel-cmt-cat source

tree. It covers some general guidelines, the preferred style and formatting

for source files, additional requirements like documentation

and development workflow. The goal of this document is to walk you through

the concepts and specifics that should be understood while contributing

to intel-cmt-cat.

Reporting Bugs

==============

Bugs should be reported via GitHub issues. The description should include

a platform name, OS and kernel version, PQoS library version and detailed

information how to reproduce the bug.

Suggesting Enhancements

=======================

Improvements should be reported via GitHub issues or pull requests.

Creating Pull Requests

======================

Pull requests should be created using standard procedure available on GitHub.

It is important to fill in all required information into a template. For major

modifications (e.g. adding a new feature, refactoring), for effective

development, it is recommended to share high level document with core

development team via GitHub issue so that one can ask questions if one foresees

issues that may occur in existing development.

Coding Style Guides

===================

General Guidelines

==================

The rules and guidelines given in this document cannot cover every situation,

so the following general guidelines should be used as a fallback:

The code style should be consistent within each individual file.

In the case of creating new files, the style should be consistent within

each file in a given directory or module. The primary reason for coding

standards is to increase code readability and comprehensibility, therefore

always use whatever option will make the code easier to read. Line length

is recommended to be not more than 80 characters, including comments.

C

=

Formatting using checkpatch.pl

==============================

To format your code please use checkpatch.pl script (version 0.32) from

Linux kernel

(https://github.com/torvalds/linux/blob/master/scripts/checkpatch.pl).

Indentation

===========

Tabs are 8 characters and thus indentations are also 8 characters.

It should be consistent within each part of the code. When adding a new file,

spaces should be used over tabs.

C Comment Style

===============

Usual Comments

==============

These comments should be used in normal cases. To document a public API,

a doxygen-like format must be used: refer to Doxygen Guidelines

(http://www.doxygen.nl/manual/docblocks.html).

/*

 * VERY important single-line comments look like this.

 */

/* Most single-line comments look like this. */

/*

 * Multi-line comments look like this. Make them real sentences. Fill

 * them so they look like real paragraphs.

 */

License Header

==============

Each file should begin with a special comment containing the appropriate

copyright and license for the file. Generally this is the BSD License,

except for code for Linux Kernel modules. After any copyright header,

a blank line should be left before any other contents, e.g. include statements

in a C file.

Preprocessor Directives (Header Includes)

=========================================

Include files from the local application directory are included using quotes,

while includes from other paths are included using angle brackets: “<>”.

Example:

#include <stdlib.h>

#include <string.h>

#include <pthread.h>

#include "pqos.h"

#include "cap.h"

#include "allocation.h"

#include "os_allocation.h"

#include "machine.h"

#include "types.h"

#include "log.h"

Header File Guards

==================

Headers should be protected against multiple inclusion with the usual:

#ifndef _FILE_H_

#define _FILE_H_

/* Code */

#endif /* _FILE_H_ */

Macros

======

You can define a macro similar in C using #define preprocessor directive.

For example:

/**

 * ---------------------------------------

 * Local macros

 * ---------------------------------------

 */

/**

 * Allocation & Monitoring association MSR register

 * - bits [63..32] QE COS

 * - bits [31..10] Reserved

 * - bits [9..0] RMID

 */

#define PQOS_MSR_ASSOC             0xC8F

#define PQOS_MSR_ASSOC_QECOS_SHIFT 32

#define PQOS_MSR_ASSOC_QECOS_MASK  0xffffffff00000000ULL

Public APIs in libpqos

======================

All functions that are exposed by the library must have their prototypes

defined in lib/pqos.h.

Python

======

Python code in this repository except examples has associated .pylintrc

configuration file for Pylint tool. The code should be rated at 10.0/10.0

by this linter. Optionally it is allowed to disable some checks in code using

comments.

Perl

====

Perl code should be checked (and reformatted if necessary) using Perltidy tool.

These are the recommended flags:

-bar - keep the brace on the right even for multiple-line test expressions

-ce - cuddled else

-pt=2 - parentheses horizontal tightness - space is never used

-sbt=2 - square brackets horizontal tightness - space is never used

-bbt=2 - code block curly braces horizontal tightness - space is never used

-et=4 - entab leading whitespace with one tab character for each 4 spaces

-baao - "break after all operators"

-nsfs - no space before a semicolon in a for statement

-vtc=1 - do not break before a closing token which is followed by a semicolon

or another closing token, and is not in a list environment

-ci=4 - continuation indentation - extra indentation spaces applied when

a long line is broken, 4 spaces

Documentation

=============

Please make sure to update documentation when necessary. If not possible

(e.g. not allowed to edit wiki), propose necessary changes.

Git Commit Messages

===================

Git commit messages should start with a short 50 character or less summary

in a single paragraph. Ideally, it should start with a short prefix

followed by a colon describing which part of the code it modifies

e.g. "pqos: show supported features".

Development Workflow

====================

Clone a repository in the usual way, for example:

git clone https://github.com/intel/intel-cmt-cat

Once your local repository is set up as above, you must use

the following workflow.

Make sure you have the latest upstream changes:

git remote update

git checkout master

git pull origin master

Committing a Change

===================

Make your changes, commit them, and submit them for review:

git commit -a

To see how to create pull requests on GitHub, please refer to "About pull

requests" help page (https://help.github.com/articles/about-pull-requests/).

Note: Please ensure that you have your username and email address set correctly

to let other developers know about your contribution:

git config --global user.name "Firstname Lastname"

git config --global user.email "your_email@youremail.com"

Licenses

========

The code in this repository is licensed under BSD license (see LICENSE file).