Skip to content

Commit 7f920b5

Browse files
roubkaralberttorosyan
roubkar
and
alberttorosyan
authored
[doc] Update Contributing Guide
Co-authored-by: Albert Torosyan <[email protected]>
1 parent 5b587da commit 7f920b5

File tree

2 files changed

+207
-68
lines changed

2 files changed

+207
-68
lines changed

‎CODE_OF_CONDUCT.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
## Code of Conduct
2+
3+
### Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to making participation in our project and
7+
our community a harassment-free experience for everyone, regardless of age, body
8+
size, disability, ethnicity, gender identity and expression, level of experience,
9+
nationality, personal appearance, race, religion, or sexual identity and
10+
orientation.
11+
12+
### Our Standards
13+
14+
Examples of behavior that contributes to creating a positive environment
15+
include:
16+
17+
* Using welcoming and inclusive language
18+
* Being respectful of differing viewpoints and experiences
19+
* Gracefully accepting constructive criticism
20+
* Focusing on what is best for the community
21+
* Showing empathy towards other community members
22+
23+
Examples of unacceptable behavior by participants include:
24+
25+
* The use of sexualized language or imagery and unwelcome sexual attention or
26+
advances
27+
* Trolling, insulting/derogatory comments, and personal or political attacks
28+
* Public or private harassment
29+
* Publishing others' private information, such as a physical or electronic
30+
address, without explicit permission
31+
* Other conduct which could reasonably be considered inappropriate in a
32+
professional setting
33+
34+
### Our Responsibilities
35+
36+
Project maintainers are responsible for clarifying the standards of acceptable
37+
behavior and are expected to take appropriate and fair corrective action in
38+
response to any instances of unacceptable behavior.
39+
40+
Project maintainers have the right and responsibility to remove, edit, or
41+
reject comments, commits, code, wiki edits, issues, and other contributions
42+
that are not aligned to this Code of Conduct, or to ban temporarily or
43+
permanently any contributor for other behaviors that they deem inappropriate,
44+
threatening, offensive, or harmful.
45+
46+
### Scope
47+
48+
This Code of Conduct applies both within project spaces and in public spaces
49+
when an individual is representing the project or its community. Examples of
50+
representing a project or community include using an official project e-mail
51+
address, posting via an official social media account, or acting as an appointed
52+
representative at an online or offline event. Representation of a project may be
53+
further defined and clarified by project maintainers.
54+
55+
### Enforcement
56+
57+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58+
reported by contacting the project team at [email protected]. All
59+
complaints will be reviewed and investigated and will result in a response that
60+
is deemed necessary and appropriate to the circumstances. The project team is
61+
obligated to maintain confidentiality with regard to the reporter of an incident.
62+
Further details of specific enforcement policies may be posted separately.
63+
64+
Project maintainers who do not follow or enforce the Code of Conduct in good
65+
faith may face temporary or permanent repercussions as determined by other
66+
members of the project's leadership.
67+
68+
### Attribution
69+
70+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
71+
available at [http://contributor-covenant.org/version/1/4][version]
72+
73+
[homepage]: http://contributor-covenant.org
74+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md

+133-68
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,157 @@
11
# Contributing
22

3-
When contributing to this repository, please first discuss the change you wish to make via issue,
4-
email, or any other method with the owners of this repository before making a change.
3+
Thanks for your interest in helping improve Aim! 🎉
54

6-
Please note we have a code of conduct, please follow it in all your interactions with the project.
5+
## Before Contributing
76

8-
## Pull Request Process
7+
As with most projects, prior to starting to code on a bug fix or feature request, please post in the respective GitHub issue saying you want to volunteer, and then wait for a positive response. And if there is no issue for it yet, create it first.
98

10-
1. Ensure any install or build dependencies are removed before the end of the layer when doing a
11-
build.
12-
2. Update the README.md with details of changes to the interface, this includes new environment
13-
variables, exposed ports, useful file locations and container parameters.
14-
3. Increase the version numbers in any examples files and the README.md to the new version that this
15-
Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
16-
4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you
17-
do not have permission to do that, you may request the second reviewer to merge it for you.
9+
This helps make sure:
10+
1. Two people aren't working on the same thing.
11+
2. This is something Aim's maintainers believe should be implemented/fixed.
12+
3. Any API, UI, or deeper architectural changes that need to be implemented have been fully thought through by the community together with Aim's maintainers.
1813

19-
## Code of Conduct
14+
Please follow [Aim Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md) in all your interactions with the project.
2015

21-
### Our Pledge
16+
## Governance
2217

23-
In the interest of fostering an open and welcoming environment, we as
24-
contributors and maintainers pledge to making participation in our project and
25-
our community a harassment-free experience for everyone, regardless of age, body
26-
size, disability, ethnicity, gender identity and expression, level of experience,
27-
nationality, personal appearance, race, religion, or sexual identity and
28-
orientation.
18+
This section describes governance processes we follow in developing Aim.
2919

30-
### Our Standards
20+
### Persons of Interest
3121

32-
Examples of behavior that contributes to creating a positive environment
33-
include:
22+
#### Authors
3423

35-
* Using welcoming and inclusive language
36-
* Being respectful of differing viewpoints and experiences
37-
* Gracefully accepting constructive criticism
38-
* Focusing on what is best for the community
39-
* Showing empathy towards other community members
24+
- Gev Soghomonyan ([SGevorg](https://github.com/SGevorg))
25+
- Gor Arakelyan ([gorarakelyan](https://github.com/gorarakelyan))
4026

41-
Examples of unacceptable behavior by participants include:
27+
#### Primary Maintainers
4228

43-
* The use of sexualized language or imagery and unwelcome sexual attention or
44-
advances
45-
* Trolling, insulting/derogatory comments, and personal or political attacks
46-
* Public or private harassment
47-
* Publishing others' private information, such as a physical or electronic
48-
address, without explicit permission
49-
* Other conduct which could reasonably be considered inappropriate in a
50-
professional setting
29+
- Albert Torosyan ([alberttorosyan](https://github.com/alberttorosyan))
30+
- Karen Hambardzumyan ([mahnerak](https://github.com/mahnerak))
31+
- Ruben Karapetyan ([roubkar](https://github.com/roubkar))
5132

52-
### Our Responsibilities
33+
#### Core Contributors
5334

54-
Project maintainers are responsible for clarifying the standards of acceptable
55-
behavior and are expected to take appropriate and fair corrective action in
56-
response to any instances of unacceptable behavior.
35+
- Arsen Alkamyan ([arsengit](https://github.com/arsengit))
36+
- Arthur Poghosyan ([devfox-se](https://github.com/devfox-se))
37+
- Hamik Hambardzumyan ([Hamik25](https://github.com/Hamik25))
38+
- Karo Muradyan ([KaroMourad](https://github.com/KaroMourad))
39+
- Mihran Vanyan ([mihran113](https://github.com/mihran113))
40+
- Ruben Aprikyan ([rubenaprikyan](https://github.com/rubenaprikyan))
41+
- Vardges Hovhannisyan ([VkoHov](https://github.com/VkoHov))
5742

58-
Project maintainers have the right and responsibility to remove, edit, or
59-
reject comments, commits, code, wiki edits, issues, and other contributions
60-
that are not aligned to this Code of Conduct, or to ban temporarily or
61-
permanently any contributor for other behaviors that they deem inappropriate,
62-
threatening, offensive, or harmful.
43+
### Releases
6344

64-
### Scope
45+
We release a new minor version (e.g., 3.8.0) every two week and patch releases on demand. The minor versions contain new features, bugfixes and also all previous bugfixes included in previous patch releases. With every release, we publish a CHANGELOG where we list enhancements and fixes.
6546

66-
This Code of Conduct applies both within project spaces and in public spaces
67-
when an individual is representing the project or its community. Examples of
68-
representing a project or community include using an official project e-mail
69-
address, posting via an official social media account, or acting as an appointed
70-
representative at an online or offline event. Representation of a project may be
71-
further defined and clarified by project maintainers.
47+
## Contribution Process
7248

73-
### Enforcement
49+
The Aim contribution process starts with filing a GitHub issue. Aim defines six categories of issues: enhancements (feature requests), bug reports, code health improvements, peformance improvements, tests, questions.
7450

75-
Instances of abusive, harassing, or otherwise unacceptable behavior may be
76-
reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
77-
complaints will be reviewed and investigated and will result in a response that
78-
is deemed necessary and appropriate to the circumstances. The project team is
79-
obligated to maintain confidentiality with regard to the reporter of an incident.
80-
Further details of specific enforcement policies may be posted separately.
51+
Aim maintainers actively triage and respond to GitHub issues. In general, we recommend waiting for feebdack from an Aim maintainer or community member before proceeding to implement a feature or patch. This is particularly important for significant changes, and will typically be labeled during triage with `phase / exploring`.
8152

82-
Project maintainers who do not follow or enforce the Code of Conduct in good
83-
faith may face temporary or permanent repercussions as determined by other
84-
members of the project's leadership.
53+
After you have agreed upon an implementation strategy for your feature or patch with an Aim maintainer, the next step is to introduce your changes as a pull request against the Aim Repository.
8554

86-
### Attribution
55+
Once your pull request against the Aim Repository has been merged, your corresponding changes will be automatically included in the next Aim release. Every change is listed in the Aim release notes and [CHANGELOG](./CHANGELOG.md).
8756

88-
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
89-
available at [http://contributor-covenant.org/version/1/4][version]
57+
Congratulations, you have just contributed to Aim. We appreciate your contribution!
9058

91-
[homepage]: http://contributor-covenant.org
92-
[version]: http://contributor-covenant.org/version/1/4/
59+
## Developing and Testing
60+
61+
The majority of the Aim product areas is developed in Python/Cython. This includes the Storage, SDK, Tracking Server, CLI, API. Aim UI is a Web app mostly built with TypeScript and React.
62+
63+
### Developing Storage/SDK/CLI
64+
65+
Most of the backend components, including SDK, Storage, Web APIs and CLI are developed using Python/Cython.
66+
In order to start development you must install dev. requirements and the aim package itself, in editable mode.
67+
```shell
68+
pip install -r requirements.dev.txt
69+
pip install -e .
70+
```
71+
72+
Verify that Aim installed properly by running
73+
```shell
74+
aim version
75+
```
76+
or by importing aim in python REPL
77+
```python
78+
import aim
79+
```
80+
81+
#### Style Guide
82+
Aim follows PEP8 standard for style guide and uses `flake8` as a style checker. Style checks enforced
83+
as a check on GitHub Actions when new PR opened.
84+
85+
#### Testing Requirements
86+
87+
New unit-tests must be added along with the code changes. In order to setup the testing environment
88+
```shell
89+
cd tests
90+
pip install requirements.txt
91+
```
92+
93+
Aim python code unit-tests are located at `tests/` directory. Unit-tests are written in Python's `unittest` package style.
94+
[Pytest](https://docs.pytest.org) is used as a test runner/discovery tool. To make sure unit-tests are not failing run
95+
```shell
96+
pytest tests/
97+
```
98+
99+
### Developing UI
100+
101+
Aim UI is written in TypeScript. `npm` is required to build Aim UI and to run in DEV mode.
102+
You can verify that `npm` is on the PATH by running `npm -v`, and
103+
[install npm](https://www.npmjs.com/get-npm) if needed.
104+
105+
#### Style Guide
106+
107+
We use Prettier to autoformat code on presubmit.
108+
109+
#### Launching the Development UI
110+
111+
Before running the Aim UI dev server or building a distributable wheel, install npm
112+
dependencies via:
113+
114+
```shell
115+
cd aim/web/ui
116+
npm install
117+
```
118+
119+
Then you can start the dev server:
120+
121+
```shell
122+
npm start
123+
```
124+
125+
Aim UI will show logged data in at [http://localhost:3000](http://localhost:3000).
126+
127+
#### Adding New Components
128+
129+
To start building a new component you can run follwoing command:
130+
131+
```shell
132+
npm run crc
133+
```
134+
135+
136+
If you want to add a component inside UI kit you can run following command:
137+
138+
```shell
139+
npm run crc-kit
140+
```
141+
142+
These command will create a folder named `ComponentName` with all the necessary files.
143+
144+
## Writing Docs
145+
146+
Aim documentation is built using [Sphix](https://www.sphinx-doc.org) and is hosted at
147+
[Read the Docs](https://aimstack.readthedocs.io).
148+
The documentation sources are located at `docs/` directory. In order to build documentation locally
149+
run the following commands
150+
```shell
151+
pip install -r requirements.dev.txt
152+
cd docs
153+
pip install -r requirements.txt
154+
make html
155+
```
156+
157+
Documentation will be available at `docs/build/html/index.html` on your local machine.

0 commit comments

Comments
 (0)