github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/CONTRIBUTING.md (about)

     1  
     2  # Contributing to Flow Go
     3  
     4  Thank you for your interest in contributing to Flow!
     5  
     6  The following is a set of guidelines for contributing to Flow Go. These are mostly guidelines, 
     7  not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
     8  
     9  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
    10  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
    11  ## Table of Contents
    12  
    13  - [How Can I Contribute?](#how-can-i-contribute)
    14    - [Reporting Bugs](#reporting-bugs)
    15      - [Before Submitting A Bug Report](#before-submitting-a-bug-report)
    16      - [How Do I Submit A (Good) Bug Report?](#how-do-i-submit-a-good-bug-report)
    17    - [Suggesting Enhancements](#suggesting-enhancements)
    18      - [Before Submitting An Enhancement Suggestion](#before-submitting-an-enhancement-suggestion)
    19      - [How Do I Submit A (Good) Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion)
    20    - [Your First Code Contribution](#your-first-code-contribution)
    21  - [Pull Request Checklist](#pull-request-checklist)
    22  - [Style Guide](#style-guide)
    23    - [Git Commit Messages](#git-commit-messages)
    24    - [Go Style Guide](#go-style-guide)
    25  
    26  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
    27  
    28  ## How Can I Contribute?
    29  
    30  ### Reporting Bugs
    31  
    32  #### Before Submitting A Bug Report
    33  
    34  Please **search existing issues** to see if the problem has already been reported.
    35  If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one.
    36  
    37  #### How Do I Submit A (Good) Bug Report?
    38  
    39  Descriptive and detailed bug reports are incredibly valuable to help maintainers reproduce and
    40  diagnose the problem. When writing a bug report, consider the following guidelines for making
    41  it as impactful as possible.
    42  
    43  - **Use a clear and descriptive title** for the issue to identify the problem.
    44  - **Describe the exact steps which reproduce the problem** in as many details as possible.
    45    When listing steps, **don't just say what you did, but explain how you did it**.
    46  - **Provide specific examples to demonstrate the steps**.
    47    Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples.
    48    If you're providing snippets in the issue,
    49    use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
    50  - **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
    51  - **Explain which behavior you expected to see instead and why.**
    52  - **Include error messages and stack traces** which show the output / crash and clearly demonstrate the problem.
    53  
    54  Provide more context by answering these questions:
    55  
    56  - **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens
    57    and under which conditions it normally happens.
    58  
    59  Include details about your configuration and environment:
    60  
    61  - **What is the version of Flow you're using**?
    62  - **What is the name and version of the Operating System you're using**?
    63  
    64  ### Suggesting Enhancements
    65  
    66  #### Before Submitting An Enhancement Suggestion
    67  
    68  Please **search existing issues** to see if the enhancement has already been suggested.
    69  If it has, add a comment to the existing issue instead of opening a new one.
    70  
    71  #### How Do I Submit A (Good) Enhancement Suggestion?
    72  
    73  Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/).
    74  When suggesting an enhancement, consider the following guidelines for 
    75  
    76  - **Use a clear and descriptive title** for the issue to identify the suggestion.
    77  - **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
    78  - **Provide specific examples to demonstrate the steps**.
    79    Include copy/pasteable snippets which you use in those examples,
    80    as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines).
    81  - **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
    82  - **Explain why this enhancement would be useful** to users.
    83  
    84  ### Your First Code Contribution
    85  
    86  Unsure where to begin contributing to Flow Go?
    87  You can start by looking through these `good-first-issue` and `help-wanted` issues:
    88  
    89  - [Good first issues](https://github.com/onflow/flow-go/labels/good%20first%20issue):
    90    issues which should only require a few lines of code, and a test or two.
    91  - [Help wanted issues](https://github.com/onflow/flow-go/labels/help%20wanted):
    92    issues which should be a bit more involved than `good-first-issue` issues.
    93  
    94  Both issue lists are sorted by total number of comments.
    95  While not perfect, number of comments is a reasonable proxy for impact a given change will have.
    96  
    97  When you're ready to start, see the [development workflow](/README.md#development-workflow), 
    98  [PR checklist](#pull-request-checklist), and [style guide](#style-guide) for more information.
    99  
   100  ## Pull Request Checklist
   101  
   102  When you're ready for your contribution to be reviewed, please ensure it satisfies the
   103  following when creating your pull request:
   104  
   105  * Ensure your PR is up-to-date with `master` and has no conflicts
   106  * Ensure your PR passes existing tests and the linter
   107  * Ensure your PR adds relevant tests for any fixed bugs or added features
   108  * Ensure your PR adds or updates any relevant documentation
   109  
   110  A reviewer will be assigned automatically when your PR is created.
   111  
   112  We use [bors](https://github.com/bors-ng/bors-ng) merge bot to ensure that the `master` branch never breaks.
   113  Once a PR is approved, you can comment on it with the following to add your PR to the merge queue:
   114  
   115  ```
   116  bors merge
   117  ```
   118  
   119  If the PR passes CI, it will automatically be pushed to the `master` branch. If it fails, bors will comment
   120  on the PR so you can fix it.
   121  
   122  See the [documentation](https://bors.tech/documentation/) for a more comprehensive list of bors commands.
   123  
   124  ## Style Guide
   125  
   126  The following is a brief summary of the coding style used in Flow. 
   127  
   128  The best way to familiarize yourself with the patterns and styles in use in this project 
   129  is to read through some code!
   130  
   131  ### Git Commit Messages
   132  
   133  - Use the present tense ("Add feature" not "Added feature")
   134  - Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
   135  - Limit the first line to 72 characters or less
   136  - Reference issues and pull requests liberally after the first line
   137  
   138  ### Go Style Guide
   139  
   140  The majority of this project is written in Go.
   141  
   142  We try to follow the coding guidelines from the Go community.
   143  
   144  - Code should be formatted using `go fmt`
   145  - Code should pass the linter: `make lint`
   146  - Code should follow the guidelines covered in
   147    [Effective Go](http://golang.org/doc/effective_go.html)
   148    and [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
   149  - Code should be commented
   150  - Code should pass all tests: `make test`
   151