CONTRIBUTING

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