Much of this guide was adopted from AXLearn.
- Please do not commit broken code to any branch.
- Only commit stable config files. Config files that are in development should not be committed.
- Use pull requests (PR) to the merge in code. Do not develop on the main branch.
We follow the Google Python Style Guide.
To avoid confusion around naming, respect code consistency in the repo, including but not limited to naming conventions and code structure.
If you have not already, we recommend setting up pre-commit, which runs some of the linters/formatters prior to each commit. The same checks will be required to pass in CI, so this will help make the development process smoother.
Functions and methods must be annotated with types. We use pytype for type checking.
All PRs must be made with the default template provided in the repository.
Before embarking on a major PR, send out a sketch PR (including the high level design notes in the PR description) to solicit feedback first.
It is more manageable for both the author and reviewers to have small PRs that can be quickly reviewed and merged.
When selecting multiple reviewers, use "Assignees" to indicate that approvals from specific reviewers are required before merging.
The PR authors are expected to reply to each comment they have addressed, e.g., with "Done". However, they should refrain from resolving the comments -- instead, let the reviewers do so.
When addressing a comment, pay attention to other places where the same comment may apply, so that the reviewer does not have to repeat the comment.
When a PR is ready for another round of review, click re-request review to notify the reviewer.
Although not strictly enforced, a general etiquette is to wait for all reviewers who have left comments to approve the PR prior to merging, even if the PR has already received an approval.
In some cases, the comments may be "nits" and appropriate for addressing in follow-up PRs. We encourage authors to give a heads up to reviewers prior to merging a PR with unresolved comments by leaving PR comments (e.g. "Will address in a follow-up") as well as leaving a TODO where applicable.
People on the team should feel free to add themselves as reviewers and/or to assignees.
Consider prioritizing reviews over writing one's own code. This will make the entire team more productive.
Code review does not end with merge of the PR. Reviewers should feel free to add comments after the merge, which can be addressed in follow-up PRs.
Code that refers to (or is adapted from) other sources must explicitly reference the original source by providing a link in the docstring of the corresponding function, class, etc.
Code that is adapted from papers should have clear Reference: section in the docstring that provides a complete reference (with link) to the original paper. Links to ArXiv papers are preferred to avoid paywalls.
In some cases it's useful to track future work ("TODOs").
TODOs should have the format TODO(username1,username2) indicating the contributor(s) responsible for addressing the TODO.
Please use your actual GitHub username as opposed to an alias to avoid ambiguity.
For larger work items, consider creating a GitHub issue to track progress.