Skip to main content

Contributing

Thank you for investing your time in contributing to our project!

Read our Code of Conduct to keep our community approachable and respectable.

In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.

New contributor guide​

To get an overview of the project, read the README. Here are some resources to help you get started with open source contributions:

Getting started​

You can contribute to the project in several ways:

Issues​

Create a new issue​

If you spot a problem, search if an issue already exists. If a related issue doesn't exist, you can open a new issue using a relevant issue form.

Solve an issue​

Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. See How to use Labels for more information. As a general rule, we don’t assign issues to anyone. If you find an issue to work on, you are welcome to open a PR with a fix.

How to use Labels​

Labels can help you find an issue you'd like to help with.

  • The help wanted label is for problems or updates that anyone in the community can start working on.
  • The good first issue label is for problems or updates we think are ideal for beginners.
  • The bug label is for bugs or problems. These will usually require some knowledge of TypeScript to fix.
  • The enhancement label is for improvements of existing functionality. These will usually require some knowledge of TypeScript to implement.
  • The feature label is for feature suggestions. These will usually require some knowledge of TypeScript to implement.
  • The question label is for questions about the project. These will usually require some knowledge on how to use the project but not necessarily implementation know-how.

Make Changes​

  1. Fork the repository so that you can make your changes without affecting the original project until you're ready to merge them.
  2. Install or update to Node.js to the latest LTS release or see the specified node engine version in package.json. For more information, see Development Guidelines.
  3. Create a working branch and start with your changes!

Commit your update​

Commit the changes once you are happy with them. Don't forget to do a self-review of the PR to speed up the review process⚡.

All commits must follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types​

TypeWhen to use
featA new feature
fixA bug fix
docsDocumentation-only changes
styleFormatting, missing semicolons, etc. (no logic change)
refactorCode change that is neither a fix nor a feature
perfA performance improvement
testAdding or updating tests
choreBuild process, dependency updates, tooling
ciCI/CD configuration changes

Scope (optional)​

Use the affected component as the scope, e.g.:

  • feat(attachment), fix(processor), docs(config), chore(deps)

Examples​

feat(attachment): add support for inline image extraction
fix(processor): handle empty thread list gracefully
docs: add conventional commits section to CONTRIBUTING.md
chore(deps): update class-transformer to 0.6.0

Breaking Changes​

Append ! after type/scope and add a BREAKING CHANGE: footer:

feat(config)!: rename markProcessedMode to markProcessedMethod

BREAKING CHANGE: The config key `markProcessedMode` has been renamed to `markProcessedMethod`.

Pull Request​

When you're finished with the changes, create a pull request, also known as a PR.

  • Fill the template so that we can review your PR. This template helps reviewers understand your changes as well as the purpose of your pull request.
  • Don't forget to link PR to issue if you are solving one.
  • Enable the checkbox to allow maintainer edits so the branch can be updated for a merge. Once you submit your PR, a team member will review your proposal. We may ask questions or request additional information.
  • We may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
  • As you update your PR and apply changes, mark each conversation as resolved.
  • If you run into any merge issues, checkout this git tutorial to help you resolve merge conflicts and other issues.

Your PR is merged​

Congratulations 🎉🎉 The project team thanks you ✨.

Development Guide​

Development Flow​

See the steps at Pull Request for instructions on forking.

# Pre-requisites: Make sure a recent Node.js LTS version is installed

# Clone the repository and navigate to the project folder
git clone https://github.com/ahochsteger/gmail-processor.git
cd gmail-processor

# Install dependencies
npm install

# Perform changes
code .

# Run pre-commit tasks to make sure the code is in an acceptable state to be commited
# (clean, build, run tests, update docs, do some sanity checks, ...)
npm run pre-commit

The recommended IDE for this project is Visual Studio Code, but any other IDEs with support for TypeScript and NPM will do. Make sure to configure the IDE to respect the Code Style settings.

Code Style​

We use Prettier to automatically format our code and ensure a consistent style. It is recommended to configure your IDE to format the code (e.g. on saving) using Prettier.

Testing Locally​

Please add/update the tests for any change to keep the codebase in a well-tested state. For every source file *.ts the corresponding test file is named *.spec.ts and they are implemented using Jest as the testing framework. Remote services are mocked (see MockFactory.ts) to simplify local testing in isolation.

After the changes and tests are done run the pre-commit script that validates the changes and updates all generated artifacts (like documentation, examples, JSON schema files, ...) and include all updated files in your commit.

Automated Reviews & Assistance​

To maintain code quality and security, several automated tools assist in the review process:

  • Renovate: Keeps dependencies up to date. You may see PRs from renovate[bot].
  • Snyk: Scans for security vulnerabilities. Check the "Security" tab or PR comments for results.
  • SonarSource: Performs static analysis. It will comment on PRs with identified issues (bugs, smells, etc.).
  • Gemini Code Assist: An AI assistant that may provide automated feedback or suggestions on your PR to help speed up the review.
  • Jules: Provides additional AI-powered coding assistance.

Please review any feedback from these tools as they help ensure your contribution follows our standards before a manual review.

Beta Testing on Google Apps Script​

Use the following Script ID in combination with the version HEAD to test and give feedback before changes are released:

1yhOQyl_xWtnGJn_bzlL7oA4d_q5KoMyZyWIqXDJX1SY7bi22_lpjMiQK

Development Resources​

A list of tools, libraries and frameworks that are used for development:

Helpful resources about development for Google Apps Script: