github.com/vmware/govmomi@v0.51.0/CONTRIBUTING.md (about)

     1  # Contributing to `govmomi`
     2  
     3  tl;dr
     4  
     5  - Sign your commits, unless you've signed the CLA
     6  - Include a component `prefix:` in your commit message, if applicable
     7  - Squash fixup commits and force push to your branch
     8  
     9  ## Getting started
    10  
    11  First, fork the repository on GitHub to your personal account.
    12  
    13  Change `$USER` in the examples below to your Github username if they are not the
    14  same.
    15  
    16  ```bash
    17  git clone https://github.com/vmware/govmomi.git && cd govmomi
    18  
    19  # prevent accidentally pushing to vmware/govmomi
    20  git config push.default nothing
    21  git remote rename origin vmware
    22  
    23  # add your fork
    24  git remote add $USER git@github.com:$USER/govmomi.git
    25  
    26  git fetch -av
    27  ```
    28  
    29  ## Contribution Flow
    30  
    31  This is a rough outline of what a contributor's workflow looks like:
    32  
    33  - Create an issue describing the feature/fix
    34  - Create a topic branch from where you want to base your work.
    35  - Make commits of logical units.
    36  - [Sign](#sign-off-your-work) your commits.
    37  - Make sure your commit messages are in the proper format (see below).
    38  - Push your changes to a topic branch in your fork of the repository.
    39  - Submit a pull request to `vmware/govmomi`.
    40  
    41  See [below](#format-of-the-commit-message) for details on commit best practices
    42  and **supported prefixes**, e.g. `govc: <message>`.
    43  
    44  > **Note:** If you are new to Git(hub) check out [Git rebase, squash...oh
    45  > my!](https://www.mgasch.com/2021/05/git-basics/) for more details on how to
    46  > successfully contribute to an open source project.
    47  
    48  ### Sign-off Your Work
    49  
    50  Use the [Developer Certificate of Origin](https://developercertificate.org/) (DCO) on all Pull Requests.
    51  By adding this line to their commit messages, contributors *sign-off* that they adhere to the requirements of the DCO.
    52  
    53  Git provides the `-s` command-line option to append the required line
    54  automatically to the commit message:
    55  
    56  ```bash
    57  git commit -s -m 'This is my commit message'
    58  ```
    59  
    60  For an existing commit, you can also use this option with `--amend`:
    61  
    62  ```bash
    63  git commit -s --amend
    64  ```
    65  
    66  ### Example 1 - Fix a Bug in `govmomi`
    67  
    68  ```bash
    69  git checkout -b issue-<number> main
    70  git add <files>
    71  git commit -s -m "fix: ..." -m "Closes: #<issue-number>"
    72  git push $USER issue-<number>
    73  ```
    74  
    75  ### Example 2 - Add a new (non-breaking) API to `govmomi`
    76  
    77  ```bash
    78  git checkout -b issue-<number> main
    79  git add <files>
    80  git commit -s -m "Add API ..." -m "Closes: #<issue-number>"
    81  git push $USER issue-<number>
    82  ```
    83  
    84  ### Example 3 - Add a Feature to `govc`
    85  
    86  ```bash
    87  git checkout -b issue-<number> main
    88  git add <files>
    89  git commit -s -m "govc: Add feature ..." -m "Closes: #<issue-number>"
    90  git push $USER issue-<number>
    91  ```
    92  **Note**:
    93  To register the new `govc` command package, add a blank `_` import to `govmomi/govc/main.go`.
    94  
    95  ### Example 4 - Fix a Bug in `vcsim`
    96  
    97  ```bash
    98  git checkout -b issue-<number> main
    99  git add <files>
   100  git commit -s -m "vcsim: Fix ..." -m "Closes: #<issue-number>"
   101  git push $USER issue-<number>
   102  ```
   103  
   104  ### Example 5 - Document Breaking (API) Changes
   105  
   106  Breaking changes, e.g. to the `govmomi` APIs, are highlighted in the `CHANGELOG`
   107  and release notes when the keyword `BREAKING:` is used in the commit message
   108  body.
   109  
   110  The text after `BREAKING:` is used in the corresponding highlighted section.
   111  Thus these details should be stated at the body of the commit message.
   112  Multi-line strings are supported.
   113  
   114  ```bash
   115  git checkout -b issue-<number> main
   116  git add <files>
   117  cat << EOF | git commit -s -F -
   118  Add ctx to funcXYZ
   119  
   120  This commit introduces context.Context to function XYZ
   121  Closes: #1234
   122  
   123  BREAKING: Add ctx to funcXYZ()
   124  EOF
   125  
   126  git push $USER issue-<number>
   127  ```
   128  
   129  ### Stay in sync with Upstream
   130  
   131  When your branch gets out of sync with the main branch, use the
   132  following to update (rebase):
   133  
   134  ```bash
   135  git checkout issue-<number>
   136  git fetch -a
   137  git rebase main
   138  git push --force-with-lease $USER issue-<number>
   139  ```
   140  
   141  ### Updating Pull Requests
   142  
   143  If your PR fails to pass CI or needs changes based on code review, it's ok to
   144  add more commits stating the changes made, e.g. "Address review comments". This
   145  is to assist the reviewer(s) to easily detect and review the recent changes.
   146  
   147  In case of small PRs, it's ok to squash and force-push (see further below)
   148  directly instead.
   149  
   150  ```bash
   151  # incorporate review feedback
   152  git add .
   153  
   154  # create a fixup commit which will be merged into your (original) <commit>
   155  git commit -s --fixup <commit>
   156  git push $USER issue-<number>
   157  ```
   158  
   159  Be sure to add a comment to the PR indicating your new changes are ready to
   160  review, as Github does not generate a notification when you git push.
   161  
   162  Once the review is complete, squash and push your final commit(s):
   163  
   164  ```bash
   165  # squash all commits into one
   166  # --autosquash will automatically detect and merge fixup commits
   167  git rebase -i --autosquash main
   168  git push --force-with-lease $USER issue-<number>
   169  ```
   170  
   171  ### Code Style
   172  
   173  The coding style suggested by the Go community is used in `govmomi`. See the
   174  [style doc](https://github.com/golang/go/wiki/CodeReviewComments) for details.
   175  
   176  Try to limit column width to 120 characters for both code and markdown documents
   177  such as this one.
   178  
   179  ### Format of the Commit Message
   180  
   181  We follow the conventions described in [How to Write a Git Commit
   182  Message](http://chris.beams.io/posts/git-commit/).
   183  
   184  Be sure to include any related GitHub issue references in the commit message,
   185  e.g. `Closes: #<number>`.
   186  
   187  The [`CHANGELOG.md`](./CHANGELOG.md) and release page uses **commit message
   188  prefixes** for grouping and highlighting. A commit message that
   189  starts with `[prefix:] ` will place this commit under the respective
   190  section in the `CHANGELOG`.
   191  
   192  The following example creates a commit referencing the `issue: 1234` and puts
   193  the commit message in the `govc` `CHANGELOG` section:
   194  
   195  ```bash
   196  git commit -s -m "govc: Add CLI command X" -m "Closes: #1234"
   197  ```
   198  
   199  Currently the following prefixes are used:
   200  
   201  - `api:` - Use for API-related changes
   202  - `govc:` - Use for changes to `govc` CLI
   203  - `vcsim:` - Use for changes to vCenter Simulator
   204  - `chore:` - Use for repository related activities
   205  - `fix:` - Use for bug fixes
   206  - `docs:` - Use for changes to the documentation
   207  - `examples:` - Use for changes to examples
   208  
   209  If your contribution falls into multiple categories, e.g. `api` and `vcsim` it
   210  is recommended to break up your commits using distinct prefixes.
   211  
   212  ### Running CI Checks and Tests
   213  You can run both `make check` and `make test` from the top level of the
   214  repository.
   215  
   216  While `make check` will catch formatting and import errors, it will not apply
   217  any fixes. The developer is expected to do that.
   218  
   219  ## Reporting Bugs and Creating Issues
   220  
   221  When opening a new issue, try to roughly follow the commit message format
   222  conventions above.