Contributing to Elpis
Contributing to the Documentation
To help flesh out our documentation, you'll first need to install mkdocs.
The easiest way to do this is with pip install mkdocs
(or pip3
for mac users).
After that, from the project root, run mkdocs serve
to serve the local version
of the documentation. Now any changes you make should be live at localhost:8000
Adding New Pages
There are a few steps to adding a new page to the online documentation.
- Create a new markdown file for the page you want to add, at
docs/your_page.md
- If you want this page to appear in the navigation menu, you will need to edit
mkdocs.yml
to include the new page under thenav
section:
...
nav:
- Home: index.md
- About: about.md
...
- Your Page Title: your_page.md
Your should now see your page in the sidebar!
mkdocs
Development Commands
mkdocs serve
- Start the live-reloading docs server.mkdocs build
- Build the documentation site.mkdocs -h
- Print help message and exit.
For full documentation visit mkdocs.org.
Contributing Code
To be able to contribute code, you'll first need to clone the monorepo:
git clone https://github.com/CoEDL/elpis_next.git
Now create a dedicated branch for our work:
cd elpis_next
git checkout -b your_branch_name
Make sure your branch name is descriptive of the proposed changes.
Setting up the Appropriate Dev Environment
The elpis repo is split into 4 main development "sub-projects". You should only setup the parts you'll need to implement your required feature.
The Frontend Client
To get started with the frontend client, jump into its directory:
cd client
Make sure you've installed yarn.
And install the required node modules:
yarn
To start the development server:
yarn dev
Any changes you make in the frontend should be reflected immediately in your browser.
Server
To prepare the server devlopment environment, make sure you have Poetry installed,
and optionally, setup the appropriate Python version with a tool like asdf
or pyenv
.
Currently we're using Python version 3.10
Navigate to the server folder:
cd server
And install the Poetry dependencies:
poetry install
And you're ready to go!
Write Your Code
Now it's time to write some code! While doing so, here are some things you may want to keep in mind:
- We have a set of fairly opinionated linters/formatters for our stack. Make sure to run them before creating a PR.
- Write appropriate documentation for any changes you make.
- For Python code, this means google-style docstrings for any functions/classes you add.
- For tsx files, we don't currently have a standard documentation format.
- If your changes would change our online documentation, make sure to update it!
Formatting Your Code
We've decided that it's too much of a hassle to have to eyeball style-guides, and to that end, have provided some linters/formatters for front and backend development.
Frontend Linting/Formatting
Within the client folder, you can run the linter with yarn lint
.
The .eslintrc.json
and .prettierrc.js
files should work with common IDE
extensions (eslint and prettier respectively on vscode), so that the diagnostics
and formatting are provided automatically when you're editing a frontend file.
Backend Linting/Formatting
All of our Python related components of elpis use black for formatting/linting.
Within a Poetry folder (functions
or services/**
), after you've installed
the dependencies, you can run poetry run black .
to format the directory.
This can also be done through vscode extensions, but whatever floats your boat.
Testing Your Code
Before you start the process of submitting a PR, it is important to write some tests for your feature (if applicable).
For our backend, we're using pytest
and pytest-mock
for testing.
On the frontend, we don't currently have tests, but this may change in the future.
Testing Poetry Environments
From within a Poetry folder (functions
or services/**
), you can run the
full test suite with poetry run pytest
.
For the services, this isn't always recommended since in the integration tests, we perform a full training/inference run through, which can take a while.
To run the non-integration tests from within a service, you can instead run:
poetry run pytest -m 'not integration'
Which will skip those tests.
Writing Your Own Tests
When writing your own tests, I'd recommend following the style of the preexisting
tests for that folder. Generally in Poetry folders, the tests exist under the
tests
directory.
As a general naming convention for tests you write, we recommend:
test_some_function_with_x_should_do_y()
.
e.g.:
test_double
test_process_dataset_with_invalid_data_should_raise_exception
test_extract_annotations_with_elan_file_should_call_extract_elan
For the positive case where the function performs as expected, you can omit the with and should sections of the name.
We don't expect for you to write docstrings for any of the test functions you write, but as with the source code, if you're making an assertion about some expected value that might not be immediately clear in the code, there's no harm in adding a comment.
Commit Your Changes
When you're happy with the code on your computer, you need to commit your changes:
git commit -a
This should fire up your editor to write a commit message. When you have finished, save, and close to continue.
Update Your Branch
It's likely that other changes to main
may have happened while you were working.
To update your branch with these changes:
git checkout main
git pull --rebase
Now apply those changes to your branch:
git rebase my_new_branch
git checkout my_new_branch
If there are no merge conflicts, and the tests are still passing, it's time to proceed.
Forking (Public Contributors)
If you're not part of the CoEDL organisation on GitHub, you won't have push access to the elpis repository, and therefore won't be able to push your branch directly to the remote before you make a Pull Request.
Instead, what public contributors will have to do is make a fork of the repo (which can be thought of as a copy of the entire project), and then make the PR from a forked branch to the main branch on the original repository.
The steps to do so are provided below:
First, navigate to the elpis GitHub repo and click the fork button at the top right of the screen.
On the new page, click Create Fork
Now run the following command to add your fork as a remote:
git remote add fork https://github.com/<your username>/elpis_next.git
Push your feature branch to the forked repository:
git push -u fork your_branch_name
Now you should be ready to open a pull request!
Pushing Your Branch to the Remote (CoEDL Members)
If you have push access to the repository already, you don't have to make a fork and can instead run the following:
git push -u origin your_branch_name
This will create a new branch on the elpis repo from which you can make
your PR.
Opening a PR
Navigate to the repository you just pushed to (e.g. https://github.com/your-user-name/elpis_next) and click on "Pull Requests" in the top bar (just above the code). On the next page, click "New pull request" in the upper right-hand corner.
- The pull request should target the base repository
CoEDL/elpis_next
and the branchmain.
- The head repository will be your work (
your-user-name/elpis_next
), and the branch will be whatever name you gave your branch.
Click "Create pull request" when you're ready.
- Make sure that the changes you made are included in the PR.
- Fill in some details about your changes using the pull request template provided.
- If your PR address an issue, make sure to add it in the description.
When finished, click "Create pull request" again.
PR Feedback
Most pull requests will go through a few iterations before they get merged. Different contributors will sometimes have different opinions, and often, fixes/features will need to be revised.
If changes are requested, push to your forked feature branch, and those changes should now be visible on the PR.
When addressing feedback comments in a PR, if your latest commit fixes a comment from a previous revision, mark it as resolved to keep the PR clean.
While you're waiting for feedback on your pull request, open up another pull request, or give someone else feedback on theirs! They'll appreciate it in the same way that you appreciate feedback on your patches.