github.com/vmware/transport-go@v1.3.4/CONTRIBUTING_DEVELOPMENT.md (about)

     1  # Contribution process for developers
     2  
     3  If you plan on contributing code to Transport, please follow this step-by-step
     4  process to reduce the risk of significant changes being requested when you
     5  submit your pull request. We'll work with you on every step and try to be as
     6  responsive as possible.
     7  
     8  ## Implementation on a topic branch
     9  
    10  ### Prerequisites
    11  
    12  First, make sure you:
    13  
    14  - Read our [Developer Certificate of Origin](https://cla.vmware.com/dco). All
    15    contributions to this repository must be signed as described on that page.
    16    Your signature certifies that you wrote the patch or have the right to pass it
    17    on as an open-source patch.
    18  
    19  ### Getting started
    20  
    21  The topic branch will be branched from the latest `master` and named `topic/{feature-name}`. To merge any pull request into
    22  this branch, it will need 2 approvals from team members.
    23  
    24  Transport Go repository, and follow the instructions in the previous link to clone
    25  your fork and set the upstream remote to the main Transport Go repository. Because of
    26  the DCO, set your name and e-mail in the Git configuration for signing. Finally,
    27  create a local topic branch from the upstream `topic/{feature-name}` mentioned
    28  above.
    29  
    30  For instance, this setup part could look like this:
    31  
    32  ```shell
    33  ## Clone your forked repository
    34  git clone git@github.com:<github username>/transport-go.git
    35  
    36  ## Navigate to the directory
    37  cd transport-go
    38  
    39  ## Set name and e-mail configuration
    40  git config user.name "John Doe"
    41  git config user.email johndoe@example.com
    42  
    43  ## Setup the upstream remote
    44  git remote add upstream https://github.com/vmware/transport-go.git
    45  
    46  ## Check out the upstream a topic branch for your changes
    47  git fetch
    48  git checkout -b topic/feature-name upstream/topic/feature-name
    49  ```
    50  
    51  ### Public API Changes
    52  
    53  If you are making a change that changes the public API of an interface make sure
    54  to discuss this within a proposal issue with a Transport Go team member. A proposal
    55  allows us to plan out potential breaking changes if necessary and review the API
    56  changes. 
    57  
    58  ### Commits
    59  
    60  If your contribution is large, split it into smaller commits that are logically
    61  self-contained. You can then submit them as separate pull requests that we will
    62  review one by one and merge progressively into the topic branch.
    63  
    64  As a rule of thumb, try to keep each pull request under a couple of hundred lines of code,
    65  _unit tests included_. We realize this isn't always easy, and sometimes not
    66  possible at all, so feel free to ask how to split your contribution in the
    67  GitHub issue.
    68  
    69  In general, it's a good idea to start coding the services first
    70  and test them in isolation, then move to the components.
    71  
    72  For your commit message, please use the following format:
    73  
    74  ```
    75  <type>(optional scope): <description>
    76   < BLANK LINE >
    77  
    78  [optional body]
    79  [optional Github closing reference]
    80  
    81   < BLANK LINE >
    82  Signed-off-by: Your Name <your.email@example.com>
    83  ```
    84  
    85  `type` - could be one of `feature`, `fix`, `chore`, `docs`, `refactor`, `test`
    86  
    87  
    88  For example, a commit message could look like this:
    89  
    90  ```
    91  fix(bridge): add correct handling of state when performing multi-broker connections
    92  
    93  - ensures session is created and managed properly
    94  - pervents channel from remaining open once connection closes
    95  - cleans up channel manager once disconnected
    96  
    97  Close: #173
    98  
    99  Signed-off-by: Your Name <your.email@example.com>
   100  ```
   101  
   102  These documents provide guidance creating a well-crafted commit message:
   103  
   104  - [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/)
   105  - [Closing Issues Via Commit Messages](https://help.github.com/articles/closing-issues-via-commit-messages/)
   106  - [Conventional Commits ](https://www.conventionalcommits.org/en/v1.0.0-beta.4/)
   107  - [Github: Closing issues using keywords](https://help.github.com/en/articles/closing-issues-using-keywords)
   108  
   109  ### Submitting pull requests
   110  
   111  As you implement your contribution, make sure all work stays on your local topic
   112  branch. When an isolated part of the feature is complete with unit tests, make
   113  sure to submit your pull request **against the topic branch** on the main
   114  Transport Go repository instead of `master`. This will allow us to accept and merge
   115  partial changes that shouldn't make it into a production release of Transport Go yet.
   116  We expect every pull request to come with exhaustive unit tests for the
   117  submitted code.
   118  
   119  **Do not, at any point, rebase your local topic branch on newer versions of `master` while your work is still in progress!**
   120  This will create issues both for you, the reviewers, and maybe even other
   121  developers who might submit additional commits to your topic branch if you
   122  requested some help.
   123  
   124  To make sure your pull request will pass our automated testing, before submitting
   125  you should:
   126  
   127  - Make sure `go test ./...` passes!
   128    
   129  If everything passes, you can push your changes to your fork of Transport Go, and [submit a pull request](https://help.github.com/articles/about-pull-requests/).
   130  
   131  - Assign yourself to the Pull-Request
   132  - Assign proper labels for example if you are making documentation update only use `documentation`
   133  - Assign connected Issue that this PR will resolve
   134  
   135  ### Taking reviews into account
   136  
   137  During the review process of your pull request(s), some changes might be
   138  requested by Transport Go team members. If that happens, add extra commits to your
   139  pull request to address these changes. Make sure these new commits are also
   140  signed and follow our commit message format.
   141  
   142  Please keep an eye on your Pull-Request and try to address the comments, if any,
   143  as soon as possible.
   144  
   145  ### Shipping it
   146  
   147  Once your contribution is fully implemented, reviewed, and ready, we will rebase
   148  the topic branch on the newest `master` and squash down to fewer commits if
   149  needed (keeping you as the author, obviously).
   150  
   151  ```bash
   152  $ git rebase -i master
   153  
   154  # Rebase commits and resolve conflict, if any.
   155  
   156  $ git push origin branch -f
   157  ```
   158  
   159  Chances are, we will be more familiar with potential conflicts that might happen,
   160  but we can work with you if you want to solve some conflicts yourself. Once
   161  rebased, we will merge the topic branch into `master`, which involves a quick
   162  internal pull request you don't have to worry about, and we will finally delete
   163  the topic branch.
   164  
   165  At that point, your contribution will be available in the next official release
   166  of Transport Go
   167  
   168  ### Backport to an older version
   169  
   170  In some cases, you will have to backport the changes into the older version.
   171  Everything is the same here, only the target branch will be the older version
   172  that is affected. If you are an external contributor, we will handle the
   173  backport for you.