From fc8f0f10eea5166ead06f90f7e9394443a16143b Mon Sep 17 00:00:00 2001 From: AJ Schroeder <6432150+ajschroeder@users.noreply.github.com> Date: Thu, 23 Nov 2023 08:30:51 -0600 Subject: [PATCH] docs: rewrite contributing doc --- .github/CONTRIBUTING.md | 131 ++++++++++++++++++++++++++++++++++------ 1 file changed, 114 insertions(+), 17 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 07787fe..38696a7 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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 paragraph describing what changed and its impact." +- A reproducible test case or series of steps. +- Any modifications you've made relevant to the bug. +- 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) - * 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. - * 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 [open a discussion](https://github.com/ajschroeder/proxmox-packer-examples/discussions) to discuss any significant work with the maintainer(s). +1. You open an issue and link your pull request to the issue for context. +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, -AJ Schroeder +To send us a pull request, please: + +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 +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. \ No newline at end of file