Skip to content

Latest commit

 

History

History
205 lines (127 loc) · 8.54 KB

CONTRIBUTING.md

File metadata and controls

205 lines (127 loc) · 8.54 KB
Raw

Contributing

The Archway project welcomes all contributors.

This document serves as a guide for contributing to the Archway project. It provides an overview of the processes and policies established for quality collaboration and coordination. Please familiarize yourself with these guidelines and feel free to propose changes to this document for improvement.

License

Important: All 3rd party contributions to this repository are made under the Apache License 2.0, unless otherwise agreed to in writing.

1. IDE

1.1 Software Dependencies

The following software should be installed on the target system:

1.2 Fork & Clone

  1. Fork the Archway repository;
  2. Sync your fork to keep it up to date;
  3. Clone your fork to an appropriate directory in your local environment;
git clone https://github.com/${YOU}/archway.git

1.3 Install and Configure IDE

Download and install an IDE such as Visual Studio Code on your system.

Contributors may use whatever IDE they are comfortable with, however this guide will focus on VSCode.

Add the following extensions:

  1. Go - Rich Go language support for Visual Studio Code;
  2. vscode-proto3 - Protobuf 3 support for Visual Studio Code;
  3. GitLens - Git supercharged;

Update the Go extension settings: File -> Preferences -> Settings : @ext:golang.go

  • Set Go: Lint Tool to golangci-lint;
  • Set Go: Format Tool to gofumpt;

The required Go Tools may need to be downloaded by your IDE.

For CosmWasm and the language that shall not be named, please refer to the Archway Developer Portal.

2. Issues

Public collaboration and coordination are driven via issues. For a brief overview of using GitHub Issues, please read this.

  1. Find or Open an issue;
  2. Engage in constructive and thoughful discussion on the issue;
  3. Coordinate with other contributors on the issue;
  4. Follow GitHub best practices and the guidelines in the issue templates;

This repository uses the good first issue label to identify issues suitable for first-time contributors.

Ensure a proper title for the issue that clearly defines what the issue is. This will greatly assist others to easily find related issues and avoid duplication.

Make use of the following labels to provide additional context:

  • bug: Something isn't working;
  • documentation: Improvements or additions to documentation;
  • enhancement: New feature or request;
  • question: Further information is requested;

Example: Lack of Community Guidelines <- label as documentation

3. Branching

The main branch represents the latest development features and fixes. Thus, it will most likely not be compatible with running networks such as mainnet or any testnets.

Releases are found under release/#.#.x using a semantic versioning scheme {braking}.{feature}.{fix} denoting each minor version.

The main branch and release/* branches are protected and can only be updated via a Pull Request. Thus, do not make any commits to these branches directly.

For increased manageability please address one issue per branch and use the following branch name format:

<user>/<issue#>-<short_description>

4. Testing

All features and fixes must be accompanied by appropriate unit/integration tests. Please ensure to follow Go and CosmosSDK best practices regarding tests. Archway utilizes table-driven tests, as explained in this blogpost by Dave Cheney.

Simple rules for table-driven tests:

  1. Keep tests independent (ordering of tests should not impact testing);
  2. Test one construct or aspect per test;
  3. Every test should make it obvious what is being tested;

5. Pull Requests

  • All pull requests must target main;
  • Updates to release branches are cherry-picked from main;

Requirements to be merged:

  • The source branch must be up-to-date with main;
  • All commits must be signed;
  • All GitHub action checks must pass;
  • Documentation and Specs must be updated accordingly;
  • PR must be reviewed and approved;

PR Title & Description

Title format: <type>: <issue #> - <description>

Please follow the Conventional Commits standard as specified here.

Type:

Please use the following types based on the Angular convention.

  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • docs: Documentation only changes
  • feat: A new feature (minor version bump)
  • fix: A bug fix (patch version bump)
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Breaking Changes:

Indicate breaking changes by appending ! to the type, and/or including BREAKING CHANGE: ... in the footer.

The PR title is more than a mere commit message. It should convey something of substantial significance... A review of the repository pull request titles should provide a very clear progression path, that makes sense to someone visiting the repository for the first time.

Provide a clear and concise description of what has changed and why. Use full sentences with appropriate punctuation. It should be a summary of changes, taken from the major commits that make up the PR.

Do add references to any applicable issues at the very end using the notation: Fixes #123.

Example:

docs: #123 - Updates & Quality Control

Add contribution guidelines to provide an overview of the processes and policies to ensure quality collaboration and coordination within the repository.

Add security policy to detail the processes for reporting security issues and vulnerability disclosure.

Fixes #123, #125, #127

Commits & Commit Messages

Commit Messages follow the same conventions as outlined above for PR Titles.

Make smaller commits more often. This allows the commit log to tell the story of what has changed, and why.

The first line of every commit message must complete the following sentence: "This commit will..." (use imperative mood);

An optional main content (separated from the first line with a blank line) should describe or elaborate on what has changed and why. Use full sentences with appropriate punctuation.

Reference issues at the very end using the notation: Fixes #123.

Example:

docs: Add contribution guidelines

Contribution guidelines provide an overview of the processes and policies to ensure quality collaboration and coordination within the repository.

Fixes #125

See How to Write a Git Commit Message for more details.

6. Review

Verify PR Requirements:

  • PR title is appropriate;
  • PR description is sufficient;
  • Branch-name is appropriate;
  • PR target branch is main;
  • Source is up-to-date with main;
  • All commits are signed;
  • All GitHub action checks pass;
  • Documentation and Specs are updated appropriately;

General review considerations:

  • The code structure and architecture should follow Go and CosmosSDK best practices;
  • Code conventions and naming should be consistent with the overall codebase;
  • Code should be well commented, especially functions, variables and custom types;
  • Tests should not contain any Personally Identifiable Information;
  • Tests should not contain any production keys or addresses;

Approval Checklist:

  • I understand the code (what the code does and why);
  • I understand the impact (how the architecture, security & overall system is affected);
  • I accept responsibility for this code;

Only provide Approval if the above conditions are met.

Once Approval has been granted the reviewer, or original PR author, may proceed to squash & merge.