github.com/vmware/go-vcloud-director/v2@v2.24.0/CONTRIBUTING.md (about)

     1  # Contributing to go-vcloud-director
     2  
     3  Welcome! We gladly accept contributions from the community. If you wish
     4  to contribute code and you have not signed our contributor license
     5  agreement (CLA), our bot will update the issue when you open a pull
     6  request. For any questions about the CLA process, please refer to our
     7  [FAQ](https://cla.vmware.com/faq).
     8  
     9  ## Community
    10  
    11  VMware Cloud Director Go(lang) and Terraform contributors can be found here: 
    12  https://vmwarecode.slack.com, #vcd-terraform-dev
    13  
    14  ## Logging Bugs
    15  
    16  Anyone can log a bug using the GitHub 'New Issue' button.  Please use
    17  a short title and give as much information as you can about what the
    18  problem is, relevant software versions, and how to reproduce it.  If you
    19  know of a fix or a workaround include that too.
    20  
    21  ## Code Contribution Flow
    22  
    23  We use GitHub pull requests to incorporate code changes from external
    24  contributors.  Typical contribution flow steps are:
    25  
    26  - Fork the go-vcloud-director repo into a new repo on GitHub
    27  - Clone the forked repo locally and set the original go-vcloud-director repo as the upstream repo
    28  - Open an Issue in go-vcloud-director describing what you propose to do (unless the change is so trivial that an issue is not needed)
    29  - Wait for discussion and possible direction hints in the issue thread
    30  - Once you know  which steps to take in your intended contribution, make changes in a topic branch and commit (don't forget to add or modify tests too)
    31  - Update Go modules files `go.mod` and `go.sum` if you're changing dependencies.
    32  - Fetch changes from upstream and resolve any merge conflicts so that your topic branch is up-to-date
    33  - Push all commits to the topic branch in your forked repo
    34  - Submit a pull request to merge topic branch commits to upstream main
    35  
    36  If this process sounds unfamiliar have a look at the
    37  excellent [overview of collaboration via pull requests on
    38  GitHub](https://help.github.com/categories/collaborating-with-issues-and-pull-requests) for more information. 
    39  
    40  ## Coding Style
    41  
    42  Our standard for Golang contributions is to match the format of the [standard
    43  Go package library](https://golang.org/pkg).  
    44  
    45  - Run `go fmt` on all code with latest stable version of Go (`go fmt` results may vary between Go versions).  
    46  - All public interfaces, functions, and structs must have complete, grammatically correct Godoc comments that explain their purpose and proper usage.
    47  - Use self-explanatory names for all variables, functions, and interfaces.
    48  - Add comments for non-obvious features of internal implementations but otherwise let the code explain itself.
    49  - Include unit tests for new features and update tests for old ones. Refer to the [testing guide](TESTING.md) for more details.
    50  
    51  Go is pretty readable so if you follow these rules most functions
    52  will not need additional comments.
    53  
    54  See **CODING_GUIDELINES.md** for more advice on how to write code for this project.
    55  
    56  ### Commit Message Format
    57  
    58  We follow the conventions on [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
    59  
    60  Be sure to include any related GitHub
    61  issue references in the commit message.  See [GFM
    62  syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown)
    63  for referencing issues.
    64  
    65  ## Contribution Example
    66  
    67  Here is a tutorial of adding a feature to fix the foo api using
    68  GitHub account imahacker.  If you are an experienced git user feel free
    69  to adapt it to your own work style.
    70  
    71  ### Sign the Contributor License Agreement (CLA)
    72  
    73  VMware Apache-licensed projects require all contributors to sign a CLA. 
    74  Visit https://cla.vmware.com and follow steps presented there. 
    75  
    76  ### Fork the Repo
    77  
    78  Navigate to the [go-vcloud-director repo on
    79  GitHub](https://github.com/vmware/go-vcloud-director) and use the 'Fork' button to
    80  create a forked repository under your GitHub account.  This gives you a copy 
    81  of the repo for pull requests back to go-vcloud-director. 
    82  
    83  ### Clone and Set Upstream Remote
    84  
    85  Make a local clone of the forked repo and add the base go-vcloud-director
    86  repo as the upstream remote repository. The project uses Go modules so the path is up to you.
    87  
    88  ``` shell
    89  
    90  cd $GOPATH/src/github.com/vmware
    91  git clone https://github.com/imahacker/go-vcloud-director
    92  cd go-vcloud-director
    93  git remote add upstream https://github.com/vmware/go-vcloud-director.git
    94  ```
    95  
    96  The last git command prepares your clone to pull changes from the
    97  upstream repo and push them into the fork, which enables you to keep
    98  the fork up to date. More on that shortly.
    99  
   100  ### Make Changes and Commit
   101  
   102  Start a new topic branch from the current HEAD position on main and
   103  commit your feature changes into that branch.  
   104  
   105  ``` shell
   106  git checkout -b foo-api-fix-22 main
   107  # (Make feature changes)
   108  git commit -a --signoff
   109  git push origin foo-api-fix-22
   110  ```
   111  
   112  The --signoff puts your signature in the commit.  It's required by our CLA
   113  bot. 
   114  
   115  It is a git best practice to put work for each new feature in a separate
   116  topic branch and use git checkout commands to jump between them.  This
   117  makes it possible to have multiple active pull requests.  We can accept
   118  pull requests from any branch, so it's up to you how to manage them.
   119  
   120  ### Stay in Sync with Upstream
   121  
   122  From time to time you'll need to merge changes from the upstream
   123  repo so your topic branch stays in sync with other checkins.  To
   124  do so switch to your topic branch, pull from the upstream repo, and
   125  push into the fork.  If there are conflicts you'll need to [merge
   126  them now](https://stackoverflow.com/questions/161813/how-to-resolve-merge-conflicts-in-git).
   127  
   128  ``` shell
   129  git checkout foo-api-fix-22
   130  git fetch -a
   131  git pull --rebase upstream main --tags
   132  git push --force-with-lease origin foo-api-fix-22
   133  ```
   134  
   135  The git pull and push options are important.  Here are some details if you 
   136  need deeper understanding. 
   137  
   138  - 'pull --rebase' eliminates unnecessary merges
   139  by replaying your commit(s) into the log as if they happened
   140  after the upstream changes.  Check out [What is a "merge
   141  bubble"?](https://stackoverflow.com/questions/26239379/what-is-a-merge-bubble)
   142  for why this is important.  
   143  - --tags ensures that object tags are also pulled
   144  - Depending on your git configuration push --force-with-lease is required to make git update your fork with commits from the upstream repo.
   145  
   146  
   147  ### Test Changes Locally
   148  
   149  The last step before creating a Pull Request is to run the tests locally and
   150  making sure they pass. Please see the [testing guide](TESTING.md) for more
   151  details.
   152  
   153  ### Create a Pull Request
   154  
   155  To contribute your feature, create a pull request by going to the [go-vcloud-director upstream repo on GitHub](https://github.com/vmware/go-vcloud-director) and pressing the 'New pull request' button. 
   156  
   157  Select 'compare across forks' and select imahacker/go-vcloud-director as 'head fork'
   158  and foo-api-fix-22 as the 'compare' branch.  Leave the base fork as 
   159  vmware/go-vcloud-director and main. 
   160  
   161  ### Wait...
   162  
   163  Your pull request will automatically build in [Travis
   164  CI](https://travis-ci.org/vmware/go-vcloud-director/).  Have a look and correct
   165  any failures.
   166  
   167  Meanwhile a committer will look the request over and do one of three things: 
   168  
   169  - accept it
   170  - send back comments about things you need to fix
   171  - or close the request without merging if we don't think it's a good addition.
   172  
   173  ### Updating Pull Requests with New Changes
   174  
   175  If your pull request fails to pass Travis CI or needs changes based on
   176  code review, you'll most likely want to squash the fixes into existing
   177  commits.
   178  
   179  If your pull request contains a single commit or your changes are related
   180  to the most recent commit, you can simply amend the commit.
   181  
   182  ``` shell
   183  git add .
   184  git commit --amend
   185  git push --force-with-lease origin foo-api-fix-22
   186  ```
   187  
   188  If you need to squash changes into an earlier commit, you can use:
   189  
   190  ``` shell
   191  git add .
   192  git commit --fixup <commit>
   193  git rebase -i --autosquash main
   194  git push --force-with-lease origin foo-api-fix-22
   195  ```
   196  
   197  Be sure to add a comment to the pull request indicating your new changes
   198  are ready to review, as GitHub does not generate a notification when
   199  you git push.
   200  
   201  ## Final Words
   202  
   203  Thanks for helping us make the project better!