docs: rewrite contributing doc
This commit is contained in:
AJ Schroeder
131
.github/CONTRIBUTING.md
vendored
131
.github/CONTRIBUTING.md
vendored
@@ -1,28 +1,125 @@
|
|||||||
# How to contribute
|
# Contributing Guidelines
|
||||||
|
|
||||||
I'm really glad you're reading this, because community driven, open-source projects need volunteer developers.
|
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.
|
||||||
|
|
||||||
## Testing
|
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.
|
||||||
|
|
||||||
Until actual tests can be developed, I ask that you test any *major* changes to Packer builds. What's a major change? Anything other than changing CPU, RAM, disk size would be considered a major change to a build.
|
## Reporting Bugs, Features, and Enhancements
|
||||||
|
|
||||||
## Submitting changes
|
We welcome you to use the GitHub issue tracker to report bugs or suggest features and enhancements.
|
||||||
|
|
||||||
Please send a [GitHub Pull Request to proxmox-packer-examples](https://github.com/ajschroeder/proxmox-packer-examples/pull/new/main) with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).
|
When filing an issue, please check existing open, or recently closed, issues to make sure someone else hasn't already
|
||||||
|
reported the issue.
|
||||||
|
|
||||||
Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:
|
Please try to include as much information as you can. Details like these are incredibly useful:
|
||||||
|
|
||||||
$ git commit -m "A brief summary of the commit
|
- A reproducible test case or series of steps.
|
||||||
>
|
- Any modifications you've made relevant to the bug.
|
||||||
> A paragraph describing what changed and its impact."
|
- Anything unusual about your environment or deployment.
|
||||||
|
|
||||||
## Coding conventions
|
## Contributing via Pull Requests
|
||||||
|
|
||||||
Start reading the code and you'll get the hang of it. We optimize for readability:
|
Contributions via pull requests are appreciated. Before sending us a pull request, please ensure that:
|
||||||
|
|
||||||
* We indent using two spaces (soft tabs)
|
1. You [open a discussion](https://github.com/ajschroeder/proxmox-packer-examples/discussions) to discuss any significant work with the maintainer(s).
|
||||||
* We ALWAYS put spaces after list items and method parameters (`[1, 2, 3]`, not `[1,2,3]`), around operators (`x += 1`, not `x+=1`), and around hash arrows.
|
1. You open an issue and link your pull request to the issue for context.
|
||||||
* This is open source software. Consider the people who will read your code, and make it look nice for them. It's sort of like driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth as possible.
|
1. You are working against the latest source on the `develop` branch.
|
||||||
|
1. You check existing open, and recently merged, pull requests to make sure someone else hasn't already addressed
|
||||||
|
the problem.
|
||||||
|
|
||||||
Thanks,
|
To send us a pull request, please:
|
||||||
AJ Schroeder
|
|
||||||
|
1. Fork the repository.
|
||||||
|
1. Modify the source; please focus on the **specific** change you are contributing.
|
||||||
|
1. Ensure local tests pass.
|
||||||
|
1. Updated the documentation, if required.
|
||||||
|
1. Commit to your fork [using a clear commit messages](http://chris.beams.io/posts/git-commit/). We ask you to
|
||||||
|
lease use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
|
||||||
|
1. Send us a pull request, answering any default questions in the pull request.
|
||||||
|
1. Pay attention to any automated failures reported in the pull request, and stay involved in the conversation.
|
||||||
|
|
||||||
|
GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
|
||||||
|
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
|
||||||
|
|
||||||
|
### Contributor Flow
|
||||||
|
|
||||||
|
This is a rough outline of what a contributor's workflow looks like:
|
||||||
|
|
||||||
|
- 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](http://chris.beams.io/posts/git-commit/).
|
||||||
|
- Push your changes to a topic branch in your fork of the repository.
|
||||||
|
- Submit a pull request.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git remote add upstream https://github.com/ajschroeder/proxmox-packer-examples.git
|
||||||
|
git checkout -b feat/foo develop
|
||||||
|
git commit -s -a
|
||||||
|
git push origin feat/foo
|
||||||
|
```
|
||||||
|
|
||||||
|
### Staying In Sync With Upstream
|
||||||
|
|
||||||
|
When your branch gets out of sync with the `proxmox-packer-examples/develop` branch, use the following to update:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git checkout feat/foo
|
||||||
|
git fetch -a
|
||||||
|
git pull --rebase upstream develop
|
||||||
|
git push --force-with-lease origin feat/foo
|
||||||
|
```
|
||||||
|
|
||||||
|
### Updating Pull Requests
|
||||||
|
|
||||||
|
If your pull request fails to pass or needs changes based on code review, you'll most likely want to squash these
|
||||||
|
changes into existing commits.
|
||||||
|
|
||||||
|
If your pull request contains a single commit or your changes are related to the most recent commit, you can simply
|
||||||
|
amend the commit.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git add .
|
||||||
|
git commit --amend
|
||||||
|
git push --force-with-lease origin feat/foo
|
||||||
|
```
|
||||||
|
|
||||||
|
If you need to squash changes into an earlier commit, you can use:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
git add .
|
||||||
|
git commit --fixup <commit>
|
||||||
|
git rebase -i --autosquash develop
|
||||||
|
git push --force-with-lease origin feat/foo
|
||||||
|
```
|
||||||
|
|
||||||
|
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`.
|
||||||
|
|
||||||
|
### Formatting Commit Messages
|
||||||
|
|
||||||
|
We follow the conventions on [How to Write a Git Commit Message](http://chris.beams.io/posts/git-commit/).
|
||||||
|
|
||||||
|
Be sure to include any related GitHub issue references in the commit message.
|
||||||
|
|
||||||
|
See [GFM syntax](https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown) for referencing
|
||||||
|
issues and commits.
|
||||||
|
|
||||||
|
## Reporting Bugs and Creating Issues
|
||||||
|
|
||||||
|
When opening a new issue, try to roughly follow the commit message format conventions above.
|
||||||
|
|
||||||
|
## Finding Contributions to Work On
|
||||||
|
|
||||||
|
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](https://github.com/ajschroeder/proxmox-packer-examples/discussions).
|
||||||
|
|
||||||
|
## Licensing
|
||||||
|
|
||||||
|
See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
|
||||||
|
|
||||||
|
We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement)
|
||||||
|
for larger changes.
|
||||||
Reference in New Issue
Block a user