Skip to content

docs: update CONTRIBUTING.md #449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tenthirtyam merged 1 commit into from
Feb 20, 2026
Merged

docs: update CONTRIBUTING.md #449

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 85 additions & 70 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,88 @@
# Contributing Guidelines

Thank you for your interest in contributing to our project. Whether it's a bug
report, new feature, correction, or additional documentation, we greatly value
feedback and contributions from our community.

Please read through this document before submitting any issues or pull requests
to ensure we have all the necessary information to effectively respond to your
bug report or contribution.

## Reporting Bugs and Suggesting Enhancements

We welcome you to use the [GitHub issues][gh-issues] to report bugs or suggest
enhancements.

When filing an issue, please check existing open, or recently closed, issues to
make sure someone else hasn't already reported.

Please try to include as much information as you can using the issue form.
Details like these are incredibly useful:

- A reproducible test case or series of steps.
- Any modifications you've made relevant to the bug.
- Anything unusual about your environment or deployment.

## Contributing via Pull Requests

Contributions using pull requests are appreciated.

**Before** sending us a pull request, please ensure that:

1. You [open a discussion][gh-discussions] to discuss any significant work with
the maintainer(s).
2. You [open an issue][gh-issues] and link your pull request to the issue for
context.
3. You are working against the latest source on the `main` branch.
4. You check existing open, and recently merged, pull requests to make sure
someone else hasn't already addressed the problem.

To open a pull request, please:

1. Fork the repository.
2. Modify the source; please focus on the **specific** change you are
contributing.
3. Ensure local tests pass.
4. Update the documentation, if required.
5. Sign-off and commit to your fork
[using clear commit messages][git-commit]. Please use
[Conventional Commits][conventional-commits].
6. Open a pull request, answering any default questions in the pull request.
7. Pay attention to any automated failures reported in the pull request, and
stay involved in the conversation.

GitHub provides additional documentation on [forking a repository][gh-forks] and
[creating a pull request][gh-pull-requests].
We greatly value feedback and contributions from our community.

Please review this document before submitting any issues or pull requests to ensure we
have all the necessary information to effectively collaborate on your contribution.

> [!TIP]
If you need help or have questions about using the plugin, please refer to the
[documentation](https://github.com/vmware/packer-plugin-vmware/tree/main/docs) or open
a [discussion][gh-discussions].

## Issues

Use [GitHub issues][gh-issues] to report bugs or suggest enhancements using the
following guidelines.

> [!WARNING]
> Issues that do not follow the guidelines may be closed by the maintainers without
> further investigation.

Before opening an issue, please [search existing issues](https://github.com/vmware/packer-plugin-vmware/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
to avoid duplicates.

When opening an issue, use the provided issue form to ensure that you provide all the
necessary details. These details are important for maintainers to understand and
reproduce the issue.

> [!IMPORTANT]
> - Ensure that you are using a recent version of the plugin.
> - Ensure that you are using a supported version of VMware vSphere. The plugin supports versions in accordance with the [Broadcom Product Lifecycle][product-lifecycle].

> [!TIP]
> - Learn about [formatting code on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-code).
> - Learn about [referencing issues](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#referencing-issues-and-pull-requests).
> - Learn about [creating a GitHub Gist](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists).

## Pull Requests

Use GitHub pull requests to propose changes to the codebase using the following guidelines.

> [!WARNING]
> Pull requests that do not follow the guidelines may be closed by the maintainers
> without further review.

**Before** submitting a pull request, ensure that:

1. You have [opened a discussion][gh-discussions] to discuss any **significant** work with
the maintainer(s). This ensures that your contribution is aligned with the
project's direction and avoids unnecessary work.
2. You have identified or [open an issue][gh-issues]. This ensures that your contribution

Copilot AI Feb 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Inconsistent verb tense in the sentence. The phrase should be "You have identified or opened an issue" (past tense) to match the pattern used in the rest of the list items which all use "You have [past tense verb]".

Suggested change
2. You have identified or [open an issue][gh-issues]. This ensures that your contribution
2. You have identified or [opened an issue][gh-issues]. This ensures that your contribution

Copilot uses AI. Check for mistakes.
focuses on a specific topic and avoids duplicating effort.
3. You have forked the repository. Refer to the [GitHub documentation][gh-forks] for help.
3. You are working against the latest source on the `main` branch. You may need to
rebase your branch against the latest `main` branch.
4. You have created a topic branch based on `main`. Do not work directly on the `main` branch.
5. You have modified the source based on logical units of work. Focus on the specific change
you are contributing. Pull requests that contain multiple unrelated changes will be
rejected.
4. You have followed the existing style and conventions of the project.

Copilot AI Feb 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trailing whitespace at the end of the line. This should be removed for consistency and to follow standard markdown formatting conventions.

Suggested change
4. You have followed the existing style and conventions of the project.
4. You have followed the existing style and conventions of the project.

Copilot uses AI. Check for mistakes.
5. You have added tests for your changes.
5. You have generated the updated documentation and associated assets by running `make generate`.
5. You have tested building the plugin by running `make build`.
7. You have tested your changes with a local build of the plugin by running `make dev`.
9. You have verified all new and existing tests are passing by running `make test`.
10. You have used [Conventional Commits][conventional-commits] format for commit messages.
11. You have signed-off and committed your changes [using clear commit messages][git-commit].

When opening a pull request, ensure that:

1. You title your pull request using the [Conventional Commits][conventional-commits] format.
2. You provide a detailed description of the changes in the pull request template.
2. You open any work-in-progress pull requests as a draft.
3. You mark the pull request as ready for review when you are ready for it to be reviewed.
4. You follow the status checks for the pull request to ensure that all checks are passing.

Copilot AI Feb 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trailing whitespace at the end of the line. This should be removed for consistency and to follow standard markdown formatting conventions.

Copilot uses AI. Check for mistakes.
Comment on lines +54 to +75

Copilot AI Feb 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The numbered list contains duplicate and incorrect numbering. The sequence is: 1, 2, 3, 3, 4, 5, 4, 5, 5, 5, 7, 9, 10, 11. This should be a consecutive sequence from 1 to 11. The numbering should be: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11.

Suggested change
3. You are working against the latest source on the `main` branch. You may need to
rebase your branch against the latest `main` branch.
4. You have created a topic branch based on `main`. Do not work directly on the `main` branch.
5. You have modified the source based on logical units of work. Focus on the specific change
you are contributing. Pull requests that contain multiple unrelated changes will be
rejected.
4. You have followed the existing style and conventions of the project.
5. You have added tests for your changes.
5. You have generated the updated documentation and associated assets by running `make generate`.
5. You have tested building the plugin by running `make build`.
7. You have tested your changes with a local build of the plugin by running `make dev`.
9. You have verified all new and existing tests are passing by running `make test`.
10. You have used [Conventional Commits][conventional-commits] format for commit messages.
11. You have signed-off and committed your changes [using clear commit messages][git-commit].
When opening a pull request, ensure that:
1. You title your pull request using the [Conventional Commits][conventional-commits] format.
2. You provide a detailed description of the changes in the pull request template.
2. You open any work-in-progress pull requests as a draft.
3. You mark the pull request as ready for review when you are ready for it to be reviewed.
4. You follow the status checks for the pull request to ensure that all checks are passing.
4. You are working against the latest source on the `main` branch. You may need to
rebase your branch against the latest `main` branch.
5. You have created a topic branch based on `main`. Do not work directly on the `main` branch.
6. You have modified the source based on logical units of work. Focus on the specific change
you are contributing. Pull requests that contain multiple unrelated changes will be
rejected.
7. You have followed the existing style and conventions of the project.
8. You have added tests for your changes.
9. You have generated the updated documentation and associated assets by running `make generate`.
10. You have tested building the plugin by running `make build`.
11. You have tested your changes with a local build of the plugin by running `make dev`.
12. You have verified all new and existing tests are passing by running `make test`.
13. You have used [Conventional Commits][conventional-commits] format for commit messages.
14. You have signed-off and committed your changes [using clear commit messages][git-commit].
When opening a pull request, ensure that:
1. You title your pull request using the [Conventional Commits][conventional-commits] format.
2. You provide a detailed description of the changes in the pull request template.
3. You open any work-in-progress pull requests as a draft.
4. You mark the pull request as ready for review when you are ready for it to be reviewed.
5. You follow the status checks for the pull request to ensure that all checks are passing.

Copilot uses AI. Check for mistakes.
5. You stay involved in the conversation with the maintainers to ensure that your contribution
Comment on lines +60 to +76

Copilot AI Feb 20, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The numbered list contains duplicate numbering. The sequence is: 1, 2, 2, 3, 4, 5. Item 3 should be numbered as 3, not 2.

Suggested change
4. You have followed the existing style and conventions of the project.
5. You have added tests for your changes.
5. You have generated the updated documentation and associated assets by running `make generate`.
5. You have tested building the plugin by running `make build`.
7. You have tested your changes with a local build of the plugin by running `make dev`.
9. You have verified all new and existing tests are passing by running `make test`.
10. You have used [Conventional Commits][conventional-commits] format for commit messages.
11. You have signed-off and committed your changes [using clear commit messages][git-commit].
When opening a pull request, ensure that:
1. You title your pull request using the [Conventional Commits][conventional-commits] format.
2. You provide a detailed description of the changes in the pull request template.
2. You open any work-in-progress pull requests as a draft.
3. You mark the pull request as ready for review when you are ready for it to be reviewed.
4. You follow the status checks for the pull request to ensure that all checks are passing.
5. You stay involved in the conversation with the maintainers to ensure that your contribution
6. You have followed the existing style and conventions of the project.
7. You have added tests for your changes.
8. You have generated the updated documentation and associated assets by running `make generate`.
9. You have tested building the plugin by running `make build`.
10. You have tested your changes with a local build of the plugin by running `make dev`.
11. You have verified all new and existing tests are passing by running `make test`.
12. You have used [Conventional Commits][conventional-commits] format for commit messages.
13. You have signed-off and committed your changes [using clear commit messages][git-commit].
When opening a pull request, ensure that:
1. You title your pull request using the [Conventional Commits][conventional-commits] format.
2. You provide a detailed description of the changes in the pull request template.
3. You open any work-in-progress pull requests as a draft.
4. You mark the pull request as ready for review when you are ready for it to be reviewed.
5. You follow the status checks for the pull request to ensure that all checks are passing.
6. You stay involved in the conversation with the maintainers to ensure that your contribution

Copilot uses AI. Check for mistakes.
can be reviewed.

> [!TIP]
> If you have any questions about the contribution process, open a [discussion][gh-discussions].

### Contributor Flow

This is an outline of the contributor workflow:

- Create a topic branch from where you want to base your work.
- Make commits of logical units.
- Make sure your commit messages are
[in the proper format][conventional-commits].
- Push your changes to the topic branch in your fork.
- Submit a pull request. If the pull request is a work in progress, please open
as draft.

Example:

```shell
Expand All @@ -82,7 +99,7 @@ git push origin feat/add-x

### Formatting Commit Messages

We follow the conventions on [How to Write a Git Commit Message][git-commit] and
Follow the conventions on [How to Write a Git Commit Message][git-commit] and use
[Conventional Commits][conventional-commits].

Be sure to include any related GitHub issue references in the commit message.
Expand All @@ -99,7 +116,7 @@ Signed-off-by: Jane Doe <jdoe@example.com>
Ref: #123
```

### Staying In Sync With Upstream
### Stay In Sync With Upstream

When your branch gets out of sync with the `upstream/main` branch, use the
following to update:
Expand Down Expand Up @@ -134,18 +151,16 @@ git rebase --interactive --autosquash upstream/main
git push --force-with-lease origin feat/add-x
```

Be sure to add a comment to the pull request indicating your new changes are
ready to review, as GitHub does not generate a notification when you `git push`.

## Finding Contributions to Work On
When resolving review comments, mark the conversation as resolved and note the commit
SHA that addresses the review comment. This helps maintainers verify the issue has been
resolved.

Looking at the existing issues is a great way to find something to contribute
on. If you have an idea you'd like to discuss,
[open a discussion][gh-discussions].
Request a review from the maintainers when you are ready for a follow-up review.

[conventional-commits]: https://conventionalcommits.org
[gh-discussions]: https://github.com/vmware/packer-plugin-vmware/discussions
[gh-forks]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
[gh-issues]: https://github.com/vmware/packer-plugin-vmware/issues
[gh-pull-requests]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
[git-commit]: https://cbea.ms/git-commit
[product-lifecycle]: https://support.broadcom.com/group/ecx/productlifecycle