Skip to content

Latest commit

 

History

History
288 lines (206 loc) · 9.35 KB

CONTRIBUTING.md

File metadata and controls

288 lines (206 loc) · 9.35 KB
Raw

Contributing to github.com/ianlewis

This doc describes how to contribute to repositories under https://github.com/ianlewis.

First, I'd love to accept your patches and contributions to my projects!

How can I help?

There are many areas in my repositories that need help. These are managed in GitHub issues. Please let us know if you are willing to work on the issue and how you can contribute.

  • For new developers and contributors, please see issues labeled good first issue. These issues should require minimal background knowledge to contribute.
  • For slightly more involved changes that may require some background knowledge, please see issues labeled help wanted
  • For experienced developers, any of the open issues are open to contribution.

If you don't find an existing issue for your contribution feel free to create an issue.

Before you begin

Sign our Contributor License Agreement

Contributions most of my repositories must be accompanied by a Contributor License Agreement (CLA). This is part of the contributon process for projects laid out by my employer (Google). These projects will have a CLA check on PRs.

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.

If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again.

Visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.

Review our community guidelines and Code of Conduct

All of my repositories follow Google's Open Source Community Guidelines and contributors are also expected to follow my Code of Conduct. Please be familiar with them. Please see the Code of Conduct about how to report instances of abusive, harassing, or otherwise unacceptable behavior.

Providing feedback

Feedback can include bug reports, feature requests, documentation change proposals, or just general feedback. The best way to provide feedback to the project is to create an issue. Please provide as much info as you can about your project feedback.

For reporting a security vulnerability see the Security Policy.

Code contribution process

This section describes how to make a contribution to my repositories.

Create a fork

You should start by creating a fork of the repository under your own account so that you can push your commits.

Clone the Repository

Make sure you have configured git to connect to GitHub using SSH. See Connecting to GitHub with SSH for more info.

One you have done that you can clone the repository to get a checkout of the code. Substitute your username and repository name here.

git clone git@github.com:myuser/myrepo.git

Create a local branch

Create a local branch to do development in. This will make it easier to create a pull request later. You can give this branch an appropriate name.

git checkout -b my-new-feature

Development

Next you can develop your new feature or bug-fix. Please see the following sections on how to use the various tools used by this project during development.

The Makefile

Most of my repositiories make heavy use of make during development. This helps with automation of tasks locally on your machine. Type make to see a full list of Makefile targets.

Here is an example from the todos repository.

$ make
todos Makefile
Usage: make [COMMAND]

  help                 Shows all targets and help from the Makefile (this message).
Testing
  unit-test            Runs all unit tests.
  go-test              Runs Go unit tests.
  ts-test              Run TypeScript unit tests.
Benchmarking
  go-benchmark         Runs Go benchmarks.
Tools
  autogen              Runs autogen on code files.
Linters
  lint                 Run all linters.
  actionlint           Runs the actionlint linter.
  eslint               Runs the eslint linter.
  markdownlint         Runs the markdownlint linter.
  golangci-lint        Runs the golangci-lint linter.
  yamllint             Runs the yamllint linter.
Maintenance
  clean                Delete temporary files.

Linters

Most projects use the following linters depending on the programming languages used.

You do not necessarily need to have all installed but you will need to install those that you want to run them locally.

You can run all linters with the lint make target:

make lint

or individually by name:

make golangci-lint

Running tests

You can run all unit tests using the unit-test make target:

make unit-test

You can run unit tests for individual languages with the appropriate make target. These may vary a bit depending on the repository and code layout. Typing make or make help will show the full list of targets.

For example, this runs Go unit tests.

make go-test

Commit and push your code

Make sure to stage any change or new files or new files.

git add .

Commit your code to your branch. For some repositories, messages should follow the Conventional Commits format but this isn't always required.

git commit -sm "feat: My new feature"

You can now push your changes to your fork.

git push origin my-new-feature

Pull requests

Once you have your code pushed to your fork you can now created a new pull request (PR). This allows the project maintainers to review your submission.

Create a PR

You can create a new pull request via the GitHub UI or via the gh CLI tool. Create the PR as a draft to start.

gh pr create --title "feat: My new feature" --draft

Review the PR template/checklist

Some repositories will have a PR template with instructions on how to document your PR. Some will include a checklist. Please review the template doc and mark checklist items as complete before finalizing your PR.

Once you have finished you can mark the PR as "Ready for review".

Code reviews

All PR submissions require review. I use GitHub pull requests for this purpose. Consult About pull request reviews for more information on pull request code reviews. Once you have created a PR you should get a response within a few days.

Merge

After your code is approved it will be merged into the main branch! Congrats!

Conventions

This section contains info on general conventions I use in my repositories.

Code style and formatting

Most code, scripts, and documentation should be auto-formatted using a formatting tool.

  1. Go code should be is formatted using gofumpt.
  2. TypeScript code should be prettier.
  3. Python code should be formatted with black.
  4. YAML should be formatted using prettier.
  5. Markdown should be formatted using prettier.

Semantic Versioning

My repositories use Semantic Versioning for release versions.

This means that when creating a new release version, in general, given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backward compatible manner
  3. PATCH version when you make backward compatible bug fixes

Conventional Commits

PR titles should be in Conventional Commits format. Usually this is required by not always.

In general, the following prefixes are supported:

  1. fix: patches a bug
  2. feat: introduces a new feature
  3. docs: a change in the documentation.
  4. chore: a change that performs a task but doesn't change functionality, such as updating dependencies.
  5. refactor: a code change that improves code quality
  6. style: coding style or format changes
  7. build: changes that affect the build system
  8. ci: changes to CI/CD configuration files or scripts
  9. perf: change to improve performance
  10. revert: reverts a previous change
  11. test: adds missing tests or corrects existing tests