- A working installation of Git
- A GitHub Account
- Python 3.8
- Poetry 1.3.1
Fork the anton repository to your local github account.
After forking the project, clone the project locally using the one of the following commands:
$ git clone git@github.com:<your_github_username>/anton.git # If using SSH
$ git clone https://github.com/<your_github_username>/anton.git # If using HTTPS
Enter the project directory once the project has been cloned locally.
$ cd anton # enter the directory
Cloning a repository auto creates the origin
remote for the project which enables to push/pull to the forked repository.
To enable receiving the latest project updates, it is necessary to setup another remote generally named as upstream
. This also helps in submitting Pull Requests.
Use one of the following commands:
$ git remote add upstream git@github.com:karthikrangasai/anton.git # If using SSH
$ git remote add upstream https://github.com/karthikrangasai/anton.git # If using HTTPS
To verify that the remote has been added, run the following command and verify the outputs: (HTTPS version accordingly)
$ git remote -v
origin git@github.com:<your_github_username>/anton.git(fetch)
origin git@github.com:<your_github_username>/anton.git (push)
upstream git@github.com:karthikrangasai/anton.git (fetch)
upstream git@github.com:karthikrangasai/anton.git (push)
It is necessary to fetch
the latest changes from the upstream
remote to work the latest version of the project.
$ git fetch upstream
The git fetch
command fetches the latest code from all the branches on the upstream
remote and saves it locally.
To apply these changes to the local copy, it is required to rebase
the local branch with the upstream
branch.
$ git checkout master # To ensure that the destination branch is correctly set
$ git rebase upstream/master # Apply the latest changes to the local `master` branch
NOTE: rebase
assumes the destination branch as the current local branch and applies the changes from the branch provided in the command.
Before you make changes, you should always create a new branch to implement your changes.
Running the following command creates a new branch from the current branch and its current state:
$ git checkout -b feature/<small_description_of_the_feature>
NOTE: Please do not make changes on the master branch!
To ensure that changes are being made on the right branch, run the following command:
$ git branch
The active branch will have a asterisk * in front of it.
This project uses the poetry
dependency management tool. Ensure that a working installation of poetry 1.3.1 or above is installed.
Creating a virtual environment with poetry
is as easy as running the following command:
$ poetry install --all-extras
This aforementioned command creates a virtual environment, installs all the dependencies, and also editable installs the project to reflect the changes during development.
Once section 2.1
is complete, run the following command to setup pre-commit
$ poetry run pre-commit install
This aforementioned command installs the hooks (functions / tools) that before a git commit is made. These tools could be code formatting or type checking etc. that help maintain a consistent codebase.
Make the necessary changes to the required files on the custom branch that was created earlier.
NOTE: Don't use the same branch again after it has been merged using a Pull Request. Create a new branch for working on a new issue.
To ensure that the changes to the codebase do not break any other functionality and also the new tests do work, run the following command
$ poetry run pytest -vv tests
NOTE:
- Run this commands from the top level of the
anton
repo (i.e. the same directory that contains thepyproject.toml
file). - Ensure there are no failing tests.
pre-commit
does not allow to create a commit if the checks fail.
Add the files that have been changed/added to the index and call the pre-commit runner to format the files.
Add the files back to the index incase the tools like black
or isort
make any changes.
Some errors pointed by mypy
and pytest
will need manual resolving.
$ pre-commit run --verbose # Runs multiple checks and formats the code.
When pre-commit
runs successfully, the files can be committed.
$ git commit -m "A message describing your commit"
NOTE: It is recommended to fetch and rebase the local repository with the latest changes from the upstream
remote at this point. Refer to section 1.4
for that.
Push these changes to your fork with the following command:
$ git push origin feature/<small_description_of_the_feature>
Make a Pull Request to implement your changes on the main repository here.
To do so, click "New Pull Request". Then, choose your branch from your fork to push into "base:master".
When opening a PR, please link the issue corresponding to your feature using closing keywords in the PR's description, e.g. Resolves #23
.