Skip to content

Latest commit

 

History

History
135 lines (91 loc) · 7.59 KB

CONTRIBUTING.md

File metadata and controls

135 lines (91 loc) · 7.59 KB

Contributing Guidelines

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

The following is a set of guidelines for contributing to the Singularity Project. Feel free to propose changes, as this is a living document.

Singularity, including all related modules, follows the Singularity Code of Conduct.

Table Of Contents

How can I contribute?

Here at singularity, there’s always a lot of work to do. There are many ways you can support the project, from programming, writing, organizing, and more. Consider these as starting points:

  • Submit bugs: Perform a cursory search to see if the problem has already been reported. If it does exist, add a 👍 to the issue to indicate this is also an issue for you, and add a comment if there is extra information you can contribute. If it does not exist, create a new issue (using the Bug report template).

  • Write code: Once you've read this contributing guide, check out Good First Issues for well-prepared starter issues.

  • Improve or write documentation: Docs live at singularity/docs/en.

  • New ideas: Open a thread on the Discussion Board.

Pull Requests and Reviews

We review every change before merging to main, using GitHub pull requests. Try to keep PRs small, no more than 400 new/changed lines. Code reviews are easier, faster, and more effective when the diff is small.

Strive to separate refactors, renames, and significant clean-ups from changes in functionality. Break a large effort into multiple smaller PRs. Each such PR should be self-consistent, well-tested, and a clear step forward, but need not be a complete implementation of a large feature. Sometimes other strategies (like an integration branch) make more sense; propose this to your reviewers beforehand.

Merging a PR to main requires maintainer approval. The following process aims to merge code quickly and efficiently while avoiding both accidental and malicious introduction of bugs, unintended consequences, or vulnerabilities.

  1. Committers require approval from any single maintainer, before landing their own PRs (maintainers require approval from any committer).

If your PR hasn't been reviewed in 3 days, pinging reviewers via Github or community chat is welcome and encouraged.

We use the following conventions for code reviews:

  • "Approve" means approval. If there are comments and approval, it is expected that you'll address the comments before merging. Ask for clarification if you're not sure.

  • "Request Changes" means you don't have approval, and the reviewer wants another look.

  • By default, code review comments are advisory: the reviewee should consider them but doesn't have to respond or address them. Comments that start with "BLOCKING" must be addressed and responded to. If a reviewer makes a blocking comment but does not block merging (by marking the review "Add Comments" or "Approve") then the reviewee can merge if the issue is addressed.

In rare cases, a maintainer may request approval from all maintainers for a wide-reaching PR.

Reviewer Responsibilities:

Avoid lengthy design discussions in PR reviews. If the conversation snowballs, prefer to merge and spin out an issue for discussion, and then follow up on the process failure that led to needing a big design discussion in a PR.

Landing Changes

We strongly discourage merge commits on the main branch. When merging to main:

  • squash your PR's commits into one commit with an encompassing message, and
  • rebase against main so that your commit lands as a "fast-forward", without a merge commit.

At the command line, update your branch with git fetch origin +main:main; git rebase main. "Merge" your changes with git checkout main; git merge --ff-only <mybranch>, and push.

On GitHub, use the grey "updated branch" button, which adds a merge commit to your branch, but then land your changes with the "rebase and merge" or "squash and merge" options on the green merge button. Both of these will rebase your branch, squashing out any trailing merge commits in the process.

We may enable GitHub branch protections requiring that a CI build has passed on the branch, that the branch is up to date with main, or both. If either protection is not in force, committers should use their best judgement when landing an untested commit.

Issues and tracking

We use GitHub issues to track all significant work, including design, implementation, documentation and community efforts.

Good First Issues

Ready to begin? Here are well-prepared issue templates for

To pick up an issue:

  1. Assign it to yourself
  2. Ask for any clarifications via the issue
  3. Create a PR with your changes
  4. Link the PR to the issue

Additional Developer Notes

Add a new CLI command

  • Create a handler implementation under handler/* directory
  • Make proper godoc comments for the implementation
  • Add the handler function to the interface under handler/*/interface.go
  • Update the MockHandler under handler/*/interface.go
  • Create unit tests for this handler implementation
  • Create a function to document the swagger API func _(){}
  • Create corresponding API route handler in api/api.go
  • Create a CLI command under cmd/* directory
  • Update cmd/app.go to register the new command
  • Add the CLI command unit test in one of cmd/*_test.go
  • Optionally add CLI command integration tests in cmd/functional_test.go
  • Run make generate or go generate ./...
  • Add the swagger API unit test in api/api_test.go
  • Optionally add swagger API integration tests in cmd/api_test.go

Testing

  • All new code should be accompanied by unit tests. Prefer focussed unit tests to integration tests for thorough validation of behaviour. Existing code is not necessarily a good model, here.
  • Integration tests (in-process, daemon, or FAST) should test integration, not comprehensive functionality

Code Style

  • Make sure your code is formatted and pass make lint before submitting a PR.

Code Generation

  • Make sure all code generations are up-to-date before submitting a PR. To generate the code, run make generate.