Skip to content

Commit 509465d

Browse files
ruivieiraruivieira
authored
Update README.md (#184)
Add CONTRIBUTING.md
1 parent aa9da84 commit 509465d

File tree

2 files changed

+129
-69
lines changed

2 files changed

+129
-69
lines changed

‎CONTRIBUTING.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Contribution guide
2+
3+
**Want to contribute? Great!**
4+
We try to make it easy, and all contributions, even the smaller ones, are more than welcome.
5+
This includes bug reports, fixes, documentation, examples...
6+
But first, read this page (including the small print at the end).
7+
8+
## Legal
9+
10+
All original contributions to TrustyAI-explainability are licensed under the
11+
[ASL - Apache License](https://www.apache.org/licenses/LICENSE-2.0),
12+
version 2.0 or later, or, if another license is specified as governing the file or directory being
13+
modified, such other license.
14+
15+
## Issues
16+
17+
Python TrustyAI uses [GitHub to manage and report issues](https://github.com/trustyai-explainability/trustyai-explainability-python/issues).
18+
19+
If you believe you found a bug, please indicate a way to reproduce it, what you are seeing and what you would expect to see.
20+
Don't forget to indicate your Python TrustyAI, Java, and Maven version.
21+
22+
### Checking an issue is fixed in main
23+
24+
Sometimes a bug has been fixed in the `main` branch of Python TrustyAI and you want to confirm it is fixed for your own application.
25+
Testing the `main` branch is easy and you can build Python TrustyAI all by yourself.
26+
27+
## Creating a Pull Request (PR)
28+
29+
To contribute, use GitHub Pull Requests, from your **own** fork.
30+
31+
- PRs should be always related to an open GitHub issue. If there is none, you should create one.
32+
- Try to fix only one issue per PR.
33+
- Make sure to create a new branch. Usually branches are named after the GitHub ticket they are addressing. E.g. for ticket "issue-XYZ An example issue" your branch should be at least prefixed with `FAI-XYZ`. E.g.:
34+
35+
git checkout -b issue-XYZ
36+
# or
37+
git checkout -b issue-XYZ-my-fix
38+
39+
- When you submit your PR, make sure to include the ticket ID, and its title; e.g., "issue-XYZ An example issue".
40+
- The description of your PR should describe the code you wrote. The issue that is solved should be at least described properly in the corresponding GitHub ticket.
41+
- If your contribution spans across multiple repositories, use the same branch name (e.g. `issue-XYZ`).
42+
- If your contribution spans across multiple repositories, make sure to list all the related PRs.
43+
44+
### Python Coding Guidelines
45+
46+
PRs will be checked against `black` and `pylint` before passing the CI.
47+
48+
You can perform these checks locally to guarantee the PR passes these checks.
49+
50+
### Requirements for Dependencies
51+
52+
Any dependency used in the project must fulfill these hard requirements:
53+
54+
- The dependency must have **an Apache 2.0 compatible license**.
55+
- Good: BSD, MIT, Apache 2.0
56+
- Avoid: EPL, LGPL
57+
- Especially LGPL is a last resort and should be abstracted away or contained behind an SPI.
58+
- Test scope dependencies pose no problem if they are EPL or LPGL.
59+
- Forbidden: no license, GPL, AGPL, proprietary license, field of use restrictions ("this software shall be used for good, not evil"), ...
60+
- Even test scope dependencies cannot use these licenses.
61+
- To check the ALS compatibility license please visit these links:[Similarity in terms to the Apache License 2.0](http://www.apache.org/legal/resolved.html#category-a) 
62+
[How should so-called "Weak Copyleft" Licenses be handled](http://www.apache.org/legal/resolved.html#category-b)
63+
64+
- The dependency shall be **available in PyPi**.
65+
- Why?
66+
- Build reproducibility. Any repository server we use, must still run in future from now.
67+
- Build speed. More repositories slow down the build.
68+
- Build reliability. A repository server that is temporarily down can break builds.
69+
70+
- **Do not release the dependency yourself** (by building it from source).
71+
- Why? Because it's not an official release, by the official release guys.
72+
- A release must be 100% reproducible.
73+
- A release must be reliable (sometimes the release person does specific things you might not reproduce).
74+
75+
- **The sources are publicly available**
76+
- We may need to rebuild the dependency from sources ourselves in future. This may be in the rare case when
77+
the dependency is no longer maintained, but we need to fix a specific CVE there.
78+
- Make sure the dependency's pom.xml contains link to the source repository (`scm` tag).
79+
80+
- The dependency needs to use **reasonable build system**
81+
- Since we may need to rebuild the dependency from sources, we also need to make sure it is easily buildable.
82+
Maven or Gradle are acceptable as build systems.
83+
84+
- Only use dependencies with **an active community**.
85+
- Check for activity in the last year through [Open Hub](https://www.openhub.net).
86+
87+
- Less is more: **less dependencies is better**. Bloat is bad.
88+
- Try to use existing dependencies if the functionality is available in those dependencies
89+
- For example: use Apache Commons Math instead of Colt if Apache Commons Math is already a dependency
90+
91+
There are currently a few dependencies which violate some of these rules. They should be properly commented with a
92+
warning and explaining why are needed
93+
If you want to add a dependency that violates any of the rules above, get approval from the project leads.
94+
95+
### Tests and Documentation
96+
97+
Don't forget to include tests in your pull requests, and documentation (reference documentation, ...).
98+
Guides and reference documentation should be submitted to the [Python TrustyAI examples repository](https://github.com/trustyai-explainability/trustyai-explainability-python-examples).
99+
If you are contributing a new feature, we strongly advise submitting an example.
100+
101+
### Code Reviews and Continuous Integration
102+
103+
All submissions, including those by project members, need to be reviewed by others before being merged. Our CI, GitHub Actions, should successfully execute your PR, marking the GitHub check as green.
104+
105+
## Feature Proposals
106+
107+
If you would like to see some feature in Python TrustyAI, just open a feature request and tell us what you would like to see.
108+
Alternatively, you propose it during the [TrustyAI community meeting](https://github.com/trustyai-explainability/community).
109+
110+
Great feature proposals should include a short **Description** of the feature, the **Motivation** that makes that feature necessary and the **Goals** that are achieved by realizing it. If the feature is deemed worthy, then an Epic will be created.
111+
112+
## The small print
113+
114+
This project is an open source project, please act responsibly, be nice, polite and enjoy!
115+

‎README.md

Lines changed: 14 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,33 @@ Install from PyPi with
1414
pip install trustyai
1515
```
1616

17+
To install additional experimental features, also use
18+
19+
```shell
20+
pip install trustyai[extras]
21+
```
22+
1723
### Local
1824

19-
The minimum dependencies can be installed with
25+
The minimum dependencies can be installed (from the root directory) with
2026

2127
```shell
22-
pip install -r requirements.txt
28+
pip install .
2329
```
2430

2531
If running the examples or developing, also install the development dependencies:
2632

2733
```shell
28-
pip install -r requirements-dev.txt
34+
pip install '.[dev]'
2935
```
3036

3137
### Docker
3238

3339
Alternatively create a container image and run it using
3440

3541
```shell
36-
$ docker build -f Dockerfile -t ruivieira/python-trustyai:latest .
37-
$ docker run --rm -it -p 8888:8888 ruivieira/python-trustyai:latest
42+
$ docker build -f Dockerfile -t python-trustyai:latest .
43+
$ docker run --rm -it -p 8888:8888 python-trustyai:latest
3844
```
3945

4046
The Jupyter server will be available at `localhost:8888`.
@@ -51,71 +57,10 @@ and examples.
5157

5258
## Getting started
5359

54-
To initialise, import the module and initialise it. For instance,
55-
56-
```python
57-
import trustyai
58-
59-
trustyai.init()
60-
```
61-
62-
If the dependencies are not in the default `dep` sub-directory, or you want to use a custom classpath you can specify it
63-
with:
64-
65-
```python
66-
import trustyai
67-
68-
trustyai.init(path="/foo/bar/explainability-core-2.0.0-SNAPSHOT.jar")
69-
```
70-
71-
In order to get all the project's dependencies, the script `deps.sh` can be run and dependencies will be stored locally
72-
under `./dep`.
73-
74-
This needs to be the very first call, before any other call to TrustyAI methods. After this, we can call all other
75-
methods, as shown in the examples.
76-
77-
### Writing your model in Python
78-
79-
To code a model in Python you need to write it a function with takes a Python list of `PredictionInput` and returns a (
80-
Python) list of `PredictionOutput`.
81-
82-
This function will then be passed as an argument to the Python `PredictionProvider`
83-
which will take care of wrapping it in a Java `CompletableFuture` for you. For instance,
60+
### Examples
8461

85-
```python
86-
from trustyai.model import Model
87-
88-
89-
def myModelFunction(inputs):
90-
# do something with the inputs
91-
output = [predictionOutput1, predictionOutput2]
92-
return output
93-
94-
95-
model = Model(myModelFunction)
96-
97-
inputs = [predictionInput1, predictionInput2]
98-
99-
prediction = model.predictAsync(inputs).get()
100-
```
101-
102-
You can see the `sumSkipModel` in the [LIME tests](./tests/test_limeexplainer.py).
103-
104-
## Examples
105-
106-
You can look at the [tests](./tests) for working examples.
107-
108-
There are also [Jupyter notebooks available](https://github.com/trustyai-python/examples).
62+
There are several working examples available in the [examples](https://github.com/trustyai-explainability/trustyai-explainability-python-examples/tree/main/examples) repository.
10963

11064
## Contributing
11165

112-
To install `trustyai` for local development, use:
113-
114-
```shell
115-
$ cd scripts
116-
$ ./build.sh
117-
```
118-
119-
This will compile the necessary [Java libraries](https://github.com/trustyai-explainability/trustyai-explainability) and
120-
install
121-
the TrustyAI Python package, locally.
66+
Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for instructions on how to contribute to this project.

0 commit comments

Comments
 (0)