Skip to content

Contributor's Guide

Jump to bottom
Pierre Dulac edited this page Dec 19, 2022 · 6 revisions

CRMint Contributor's Guide

We will appreciate if you contribute to the CRMint project by doing any of the following:

We'd love to accept your patches and contributions to this project. There are just a few guidelines we'd like you to follow.

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution, this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Code Reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Community Guidelines

This project follows Google's Open Source Community Guidelines.

Contributor's Workflow

Forking the repo

You have to fork google/crmint repository in order to contribute to the CRMint's source code:

A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.

Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea.

— Fork a repo, GitHub Help

Cloning your fork of CRMint to your local machine

In order to set up the development environment you have to clone your CRMint repo to your local machine:

git clone git@github.com:YourUsernameOnGithub/crmint.git

Please, don't forget to replace YourUsernameOnGithub with your actual username on Github.

At this moment you might consider Running CRMint on your local machine just to get started quickly.

Implementing a Feature

  1. Find an existing issue or create a new one describing what feature is missing in CRMint and why you think it's worth to implement it. For an existing issue, first check who's assigned to it:

    • if no one assigned, assign yourself;
    • if someone already assigned, contact them before starting to work on the issue.

  2. In a separate comment provide an estimation of when you're planning to submit a pull request with the implementation of the feature. Please, don't be shy to add more comments reflecting your work progress, giving a heads up if work takes longer than expected, or pointing to the pull request with the feature implementation.

  3. If you haven't done it yet, add github.com:google/crmint.git as a read-only remote repo named upstream to your local repo cloned from your CRMint fork:

    git remote add upstream https://github.com/google/crmint.git

  4. Synchronize your dev branch with dev branch of upstream remote repo:

    git checkout dev
git fetch upstream
git merge upstream/dev

  5. Create and switch to a new branch named feature/<issue_id>, where <issue_id> is the ID of the issues describing the feature. For example:

    git checkout -b feature/42
git push -u origin feature/42

  6. Work on changes committing early and often.

  7. Cover your feature with tests.

  8. Make sure your changes don't break other tests and rewrite them if needed.

  9. Once you're happy with the implementation and with the tests, submit a pull request to the dev branch of google/crmint repo.

  10. Keep an eye on the comments to your pull request: we might require your help in improving the pull request if needed.

Fixing a Bug

  1. Find an existing issue or create a new one describing what's wrong with CRMint and how the bug could be reproduced. For an existing issue, first check who's assigned to it:

    • if no one assigned, assign yourself;
    • if someone already assigned, contact them before starting to work on the issue.

  2. In a separate comment provide an estimation of when you're planning to submit a pull request with the bugfix. Please, don't be shy to add more comments reflecting your work progress, giving a heads up if work takes longer than expected, or pointing to the pull request with the bugfix.

  3. If you haven't done it yet, add github.com:google/crmint.git as a read-only remote repo named upstream to your local repo cloned from your CRMint fork:

    git remote add upstream https://github.com/google/crmint.git

  4. Synchronize your dev branch with dev branch of upstream remote repo:

    git checkout dev
git fetch upstream
git merge upstream/dev

  5. Create and switch to a new branch named bug/<issue_id>, where <issue_id> is the ID of the issues describing the bug. For example:

    git checkout -b bug/42
git push -u origin bug/42

  6. If possible, create some tests that fail due to the bug and will successfully pass once the bug is fixed.

  7. Work on changes committing early and often.

  8. Make sure your changes don't break other tests and rewrite them if needed.

  9. Once you're happy with the bugfix and with the tests, submit a pull request to the dev branch of google/crmint repo.

  10. Keep an eye on the comments to your pull request: we might require your help in improving the pull request if needed.

Running CRMint on your local machine

Create a GCP project (if needed)

$ YOUR_PROJECT_ID="my-crmint-${RANDOM:0:4}"
$ gcloud projects create $YOUR_PROJECT_ID --enable-cloud-apis --set-as-default

Ensure you have the Application Default credentials locally

$ gcloud auth application-default login

Run CRMint locally

First, change to the CRMint's directory. Please, use a path to the directory where you have your CRMint repo cloned:

cd crmint/

Now it's time to build a Docker application and run it:

$ export GOOGLE_CLOUD_PROJECT=$YOUR_PROJECT_ID
$ docker-compose build
$ docker-compose up

Or:

$ GOOGLE_CLOUD_PROJECT=$YOUR_PROJECT_ID docker-compose build
$ GOOGLE_CLOUD_PROJECT=$YOUR_PROJECT_ID docker-compose up

Improving CRMint's Documentation

CRMint's documentation website is created using Jekyll. Most of the pages are generated from source markdown files in the docs/ directory, and CRMint workers reference is automatically generated from backends/jobs/workers/**/*.py files using custom Jekyll plugin docsource/_plugins/crmint-workers.rb.

Clone this wiki locally