Skip to content

Commit d8412d8

Browse files
PennycookPennycook
committed
Update README and Code of Conduct
Signed-off-by: John Pennycook <john.pennycook@intel.com>
1 parent 6b1541f commit d8412d8

File tree

2 files changed

+202
-61
lines changed

2 files changed

+202
-61
lines changed

‎CODE_OF_CONDUCT.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
CommunityCodeOfConduct AT intel DOT com.
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series of
86+
actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or permanent
93+
ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within the
113+
community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at
119+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120+
121+
Community Impact Guidelines were inspired by
122+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123+
124+
For answers to common questions about this code of conduct, see the FAQ at
125+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126+
[https://www.contributor-covenant.org/translations][translations].
127+
128+
[homepage]: https://www.contributor-covenant.org
129+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130+
[Mozilla CoC]: https://github.com/mozilla/diversity
131+
[FAQ]: https://www.contributor-covenant.org/faq

‎README.md

Lines changed: 71 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,38 @@
11
# Code Base Investigator
2-
Code Base Investigator (CBI) is a tool designed to help developers reason about the use of _specialization_ (i.e. code written specifically to provide support for or improve performance on some set of platforms) in a code base. Specialization is often necessary, but how a developer chooses to express it may impact code portability and future maintenance costs.
32

4-
The [definition of platform](https://doi.org/10.1016/j.future.2017.08.007) used by CBI is deliberately very flexible and completely user-defined; a platform can represent any execution environment for which code may be specialized. A platform could be a compiler, an operating system, a micro-architecture or some combination of these options.
3+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5018974.svg)](https://doi.org/10.5281/zenodo.5018974)
4+
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8679/badge)](https://www.bestpractices.dev/projects/8679)
55

6-
## Code Divergence
7-
CBI measures the amount of specialization in a code base using [code divergence](http://doi.org/10.1109/P3HPC.2018.00006), which is defined as the arithmetic mean pair-wise distance between the code-paths used by each platform.
6+
Code Base Investigator (CBI) is an analysis tool that provides insight into the
7+
portability and maintainability of an application's source code.
88

9-
At the two extremes, a code divergence of 0 means that all of the platforms use exactly the same code, while a code divergence of 1 means that there is no code shared between any of the platforms. The code divergence of real codes will fall somewhere in between.
9+
- Measure [code divergence](http://doi.org/10.1109/P3HPC.2018.00006) to
10+
understand how much code is specialized for different compilers, operating
11+
systems, hardware micro-architectures and more.
1012

11-
## How it Works
12-
![Abstract Syntax Tree](./docs/example-ast.png)
13+
- Visualize the distance between the code paths used to support different
14+
compilation targets.
1315

14-
CBI tracks specialization in two forms: source files that are not compiled for all platforms; and regions of source files that are guarded by C preprocessor directives (e.g. `#ifdef`). A typical run of CBI consists of a three step process:
15-
1) Extract source files and compilation commands from a configuration file or compilation database.
16-
2) Build an AST representing which source lines of code (LOC) are associated with each specialization.
17-
3) Record which specializations are used by each platform.
16+
- Identify stale, legacy, code paths that are unused by any compilation target.
1817

19-
## Usage
18+
- Export metrics and code path information required for P3 analysis using [other
19+
tools](https://intel.github.io/p3-analysis-library/).
2020

21-
The `codebasin` script analyzes a code base described in a YAML configuration file and produces one or more output reports. Example configuration files can be found in the [examples](./examples) directory, and see the [configuration file documentation](docs/configuration.md) for a detailed description of the configuration file format.
2221

23-
To see a complete list of `codebasin` options, run `codebasin -h`.
22+
## Table of Contents
2423

25-
> [!IMPORTANT]
26-
> In previous releases of Code Base Investigator, the main script was called `codebasin.py`. The old naming was a bug that needed to be fixed, and we made the difficult decision to rename the script ahead of the next major release.
24+
- [Dependencies](#dependencies)
25+
- [Installation](#installation)
26+
- [Getting Started](#getting-started)
27+
- [Contribute](#contribute)
28+
- [License](#license)
29+
- [Security](#security)
30+
- [Code of Conduct](#code-of-conduct)
31+
- [Citations](#citations)
2732

28-
### Summary Report
29-
The summary report (`-R summary`) gives a high-level summary of a code base, as shown below:
30-
```
31-
---------------------------------------------
32-
Platform Set LOC % LOC
33-
---------------------------------------------
34-
{} 2 4.88
35-
{GPU 1} 1 2.44
36-
{GPU 2} 1 2.44
37-
{CPU 2} 1 2.44
38-
{CPU 1} 1 2.44
39-
{FPGA} 14 34.15
40-
{GPU 2, GPU 1} 6 14.63
41-
{CPU 1, CPU 2} 6 14.63
42-
{FPGA, CPU 1, GPU 2, GPU 1, CPU 2} 9 21.95
43-
---------------------------------------------
44-
Code Divergence: 0.55
45-
Unused Code (%): 4.88
46-
Total SLOC: 41
47-
```
48-
Each row in the table shows the amount of code that is unique to a given set of platforms. Listed below the table are the computed code divergence, the amount of code in the code base that was not compiled for any platform, and the total size of the code base.
49-
50-
### Clustering Report
51-
The clustering report (`-R clustering`) consists of a pair-wise distance matrix, showing the ratio of platform-specific code to code used by both platforms. These distances are the same as those used to compute code divergence.
52-
```
53-
Distance Matrix
54-
-----------------------------------
55-
FPGA CPU 1 GPU 2 GPU 1 CPU 2
56-
-----------------------------------
57-
FPGA 0.00 0.70 0.70 0.70 0.70
58-
CPU 1 0.70 0.00 0.61 0.61 0.12
59-
GPU 2 0.70 0.61 0.00 0.12 0.61
60-
GPU 1 0.70 0.61 0.12 0.00 0.61
61-
CPU 2 0.70 0.12 0.61 0.61 0.00
62-
-----------------------------------
63-
```
64-
65-
The distances can also be used to produce a dendrogram, showing the result of hierarchical clustering by platform similarity:
66-
67-
![Dendrogram](./docs/example-dendrogram.png)
6833

6934
## Dependencies
35+
7036
- jsonschema
7137
- Matplotlib
7238
- NumPy
@@ -75,15 +41,59 @@ The distances can also be used to produce a dendrogram, showing the result of hi
7541
- PyYAML
7642
- SciPy
7743

78-
CBI and its dependencies can be installed using `setup.py`:
44+
45+
## Installation
46+
47+
The latest release of CBI is version 1.2.0. To download and install this
48+
release, run the following:
49+
7950
```
80-
python3 setup.py install
51+
git clone --branch 1.2.0 https://github.com/intel/code-base-investigator.git
52+
cd code-base-investigator
53+
pip install .
8154
```
8255

83-
The master branch of CBI is the development branch, and should not be used in production. Tagged releases are available [here](https://github.com/intel/code-base-investigator/releases).
56+
We strongly recommend installing CBI within a [virtual
57+
environment](https://docs.python.org/3/library/venv.html).
58+
59+
## Getting Started
60+
61+
After installation, run `codebasin -h` to see a complete list of options.
62+
63+
A full tutorial can be found in the [online
64+
documentation](https://intel.github.io/code-base-investigator/).
65+
66+
67+
## Contribute
68+
69+
Contributions to CBI are welcome in the form of issues and pull requests.
70+
71+
See [CONTRIBUTING](CONTRIBUTING.md) for more information.
72+
8473

8574
## License
75+
8676
[BSD 3-Clause](./LICENSE)
8777

88-
## Contributing
89-
See the [contribution guidelines](./CONTRIBUTING.md) for details.
78+
79+
## Security
80+
81+
See [SECURITY](SECURITY.md) for more information.
82+
83+
The main branch of CBI is the development branch, and should not be used in
84+
production. Tagged releases are available
85+
[here](https://github.com/intel/code-base-investigator/releases).
86+
87+
88+
## Code of Conduct
89+
90+
Intel has adopted the Contributor Covenant as the Code of Conduct for all of
91+
its open source projects. See [CODE OF CONDUCT](CODE_OF_CONDUCT.md) for more
92+
information.
93+
94+
95+
## Citations
96+
97+
If your use of CBI results in a research publication, please consider citing
98+
the software and/or the papers that inspired its functionality (as
99+
appropriate). See [CITATION](CITATION.cff) for more information.

0 commit comments

Comments
 (0)