mirror of
https://github.com/zama-ai/concrete.git
synced 2026-04-17 03:00:54 -04:00
doc(getting-started-guide): create terminology section, add section descriptions, improve some commands, fix typos
This commit is contained in:
Umut
@@ -2,22 +2,32 @@
|
||||
|
||||
## Preparation
|
||||
|
||||
Before you can start improving `hdk` you need to set up your development environment! This section will show how you can do that.
|
||||
|
||||
### Installing Python v3.8
|
||||
|
||||
You can follow [this](https://realpython.com/installing-python/) guide.
|
||||
`hdk` is a `Python` library. So `Python` should be installed to develop `hdk`. `v3.8` is recommended because our CI also uses `v3.8`.
|
||||
|
||||
### Installing Poertry
|
||||
You can follow [this](https://realpython.com/installing-python/) guide to install it (alternatively you can google `how to install python 3.8`).
|
||||
|
||||
You can follow [this](https://python-poetry.org/docs/#installation) guide.
|
||||
### Installing Poetry
|
||||
|
||||
`Poetry` is our package manager. It simplifies depenency and environment management by a lot.
|
||||
|
||||
You can follow [this](https://python-poetry.org/docs/#installation) guide to install it (this is the official guide so just use it).
|
||||
|
||||
### Cloning repository
|
||||
|
||||
Now, it's time to get the source code of `hdk`. You can use the following command to do that.
|
||||
|
||||
```shell
|
||||
git clone https://github.com/zama-ai/hdk.git
|
||||
```
|
||||
|
||||
### Setting up environment
|
||||
|
||||
We are going to make use of virtual environments. This helps to keep the project isolated from other `Python` projects in the system. The following commands will create a new virtual environment under the project directory and install dependencies to it.
|
||||
|
||||
```shell
|
||||
cd hdk
|
||||
make setup_env
|
||||
@@ -25,18 +35,38 @@ make setup_env
|
||||
|
||||
### Activating the environment
|
||||
|
||||
Finally, all we need to do is to activate the newly created environment using the following command.
|
||||
|
||||
```shell
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
### Syncing environment with the latest changes
|
||||
|
||||
From time to time, new dependencies will be added to project or the old ones will be removed. The command below will make sure the project have proper environment. So run it regularly!
|
||||
|
||||
```shell
|
||||
make sync_env
|
||||
```
|
||||
|
||||
## Terminology
|
||||
|
||||
In this section we will go over some terms that we use throughout the project.
|
||||
|
||||
- intermediate representation
|
||||
- a data structure to represent a calculation
|
||||
- basically a computation graph where nodes are either inputs or operations
|
||||
- tracing
|
||||
- act of creating intermediate representation from plain python functions
|
||||
- this is awesome to have to avoid manual intermediate representation creation
|
||||
- bounds
|
||||
- before intermediate representation is sent to the compiler, we need to know which node will output which type (e.g., uint3 vs uint5)
|
||||
- there are several ways to do this but the simplest one is to evaluate the intermediate representation with all combinations of inputs and remember the maximum and the minimum values for each node
|
||||
|
||||
## Module Structure
|
||||
|
||||
In this section, we will discuss the module structure of hdk briefly. You are encouraged to check individual `.py` files to learn more!
|
||||
|
||||
- hdk
|
||||
- common: types and utilities that can be used by multiple frontends (e.g., numpy, torch)
|
||||
- bounds_measurement: utilities for determining bounds of intermediate representation
|
||||
@@ -48,16 +78,21 @@ make sync_env
|
||||
|
||||
## Contributing
|
||||
|
||||
Now, you have a working environment, and you know what is where in the project. You are ready to contribute! Well, not so fast let's go over some other important things that you need to be careful about.
|
||||
|
||||
### Creating a new branch
|
||||
|
||||
We are using a consistent branch naming schema, and you are expected to follow it as well. Here is the format and some examples.
|
||||
|
||||
```shell
|
||||
git checkout -b (feat|fix|refactor|test|benchmark|doc|chore)/short-description
|
||||
git checkout -b {feat|fix|refactor|test|benchmark|doc|style|chore}/short-description{_$issue_id}?
|
||||
```
|
||||
|
||||
e.g.
|
||||
|
||||
```shell
|
||||
git checkout -b feat/explicit-tlu
|
||||
git checkout -b fix/tracing_indexing_42
|
||||
```
|
||||
|
||||
### Before committing
|
||||
@@ -65,19 +100,47 @@ git checkout -b feat/explicit-tlu
|
||||
Each commit to `hdk` should be comformant to the standards decided by the team. Conformance can be checked using the following commands.
|
||||
|
||||
```shell
|
||||
make -k pytest
|
||||
make -k pcc
|
||||
make pytest
|
||||
```
|
||||
|
||||
### Commiting
|
||||
|
||||
We are using a consistent commit naming schema, and you are expected to follow it as well. Here is the format and some examples.
|
||||
|
||||
```shell
|
||||
git commit -m "{feat|fix|refactor|test|benchmark|doc|style|chore}{($location)}?: description of the change"
|
||||
```
|
||||
|
||||
e.g.
|
||||
|
||||
```shell
|
||||
git commit -m "feat: implement bounds checking"
|
||||
git commit -m "feat(debugging): add an helper function to draw intermediate representation"
|
||||
git commit -m "fix(tracing): fix a bug that crashed pytorch tracer"
|
||||
```
|
||||
|
||||
### Before creating pull request
|
||||
|
||||
Commits on the latest version of `main` branch should be rebased to your branch before your PR can be accepted. This is to avoid merge commits and have a clean git log. After you commit your changes to your new branch, you can use the following commands to rebase.
|
||||
You should rebase on top of `main` branch before you create your pull request. This is to avoid merge commits and have a clean git log. After you commit your changes to your new branch, you can use the following commands to rebase.
|
||||
|
||||
```shell
|
||||
# fetch the list of active remote branches
|
||||
git fetch --all --prune
|
||||
|
||||
# checkout to main
|
||||
git checkout main
|
||||
git pull
|
||||
|
||||
# pull the latest changes to main (--ff-only is there to prevent accidental commits to main)
|
||||
git pull --ff-only
|
||||
|
||||
# checkout back to your branch
|
||||
git checkout $YOUR_BRANCH
|
||||
|
||||
# rebase on top of main branch
|
||||
git rebase main
|
||||
|
||||
# push the latest version of the local branch to remote
|
||||
git push --force
|
||||
```
|
||||
|
||||
@@ -86,7 +149,10 @@ You can learn more about rebasing in [here](https://git-scm.com/docs/git-rebase)
|
||||
The last requirement before creating your PR is to make sure you get a hundred percent code coverage. You can verify this using the following command.
|
||||
|
||||
```shell
|
||||
BB=$YOUR_BRANCH make coverage
|
||||
make pytest
|
||||
make coverage
|
||||
```
|
||||
|
||||
If your coverage is below hundred percent, you should write more tests and then create the pull request.
|
||||
Note that this will compare the coverage with `origin/main`. If you want to set a custom base branch, you can specify `BB` environment variable like so `BB=$YOUR_BASE_BRANCH make coverage`.
|
||||
|
||||
If your coverage is below hundred percent, you should write more tests and then create the pull request. If you ignore this warning and create the PR, GitHub actions will fail and your PR will not be merged anyway.
|
||||
|
||||
Reference in New Issue
Block a user