From a99998230c30e7686eb76cd3b22f1500826d9f3d Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Thu, 21 Sep 2023 17:21:26 +0000 Subject: [PATCH] Governance docs per CE PR 1226 Signed-off-by: Doug Davis --- CONTRIBUTING.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++ MAINTAINERS.md | 5 ++ README.md | 7 ++ RELEASING.md | 3 + 4 files changed, 182 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 MAINTAINERS.md create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fafbe6f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,167 @@ +# Contributing to CloudEvents' PHP SDK + +:+1::tada: First off, thanks for taking the time to contribute! :tada::+1: + +We welcome contributions from the community! Please take some time to become +acquainted with the process before submitting a pull request. There are just +a few things to keep in mind. + +# Pull Requests + +Typically, a pull request should relate to an existing issue. If you have +found a bug, want to add an improvement, or suggest an API change, please +create an issue before proceeding with a pull request. For very minor changes +such as typos in the documentation this isn't really necessary. + +## Pull Request Guidelines + +Here you will find step by step guidance for creating, submitting and updating +a pull request in this repository. We hope it will help you have an easy time +managing your work and a positive, satisfying experience when contributing +your code. Thanks for getting involved! :rocket: + +* [Getting Started](#getting-started) +* [Branches](#branches) +* [Commit Messages](#commit-messages) +* [Staying current with main](#staying-current-with-main) +* [Submitting and Updating a Pull Request](#submitting-and-updating-a-pull-request) +* [Congratulations!](#congratulations) + +## Getting Started + +When creating a pull request, first fork this repository and clone it to your +local development environment. Then add this repository as the upstream. + +```console +git clone https://github.com/mygithuborg/sdk-php.git +cd sdk-php +git remote add upstream https://github.com/cloudevents/sdk-php.git +``` + +## Branches + +The first thing you'll need to do is create a branch for your work. +If you are submitting a pull request that fixes or relates to an existing +GitHub issue, you can use the issue number in your branch name to keep things +organized. + +```console +git fetch upstream +git reset --hard upstream/main +git checkout FETCH_HEAD +git checkout -b 48-fix-http-agent-error +``` + +## Commit Messages + +Please follow the +[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary). +The first line of your commit should be prefixed with a type, be a single +sentence with no period, and succinctly indicate what this commit changes. + +All commit message lines should be kept to fewer than 80 characters if possible. + +An example of a good commit message. + +```log +docs: remove 0.1, 0.2 spec support from README +``` + +### Signing your commits + +Each commit must be signed. Use the `--signoff` flag for your commits. + +```console +git commit --signoff +``` + +This will add a line to every git commit message: + + Signed-off-by: Joe Smith + +Use your real name (sorry, no pseudonyms or anonymous contributions.) + +The sign-off is a signature line at the end of your commit message. Your +signature certifies that you wrote the patch or otherwise have the right to pass +it on as open-source code. See [developercertificate.org](http://developercertificate.org/) +for the full text of the certification. + +Be sure to have your `user.name` and `user.email` set in your git config. +If your git config information is set properly then viewing the `git log` +information for your commit will look something like this: + +``` +Author: Joe Smith +Date: Thu Feb 2 11:41:15 2018 -0800 + + Update README + + Signed-off-by: Joe Smith +``` + +Notice the `Author` and `Signed-off-by` lines match. If they don't your PR will +be rejected by the automated DCO check. + +## Staying Current with `main` + +As you are working on your branch, changes may happen on `main`. Before +submitting your pull request, be sure that your branch has been updated +with the latest commits. + +```console +git fetch upstream +git rebase upstream/main +``` + +This may cause conflicts if the files you are changing on your branch are +also changed on main. Error messages from `git` will indicate if conflicts +exist and what files need attention. Resolve the conflicts in each file, then +continue with the rebase with `git rebase --continue`. + + +If you've already pushed some changes to your `origin` fork, you'll +need to force push these changes. + +```console +git push -f origin 48-fix-http-agent-error +``` + +## Submitting and Updating Your Pull Request + +Before submitting a pull request, you should make sure that all of the tests +successfully pass. + +Once you have sent your pull request, `main` may continue to evolve +before your pull request has landed. If there are any commits on `main` +that conflict with your changes, you may need to update your branch with +these changes before the pull request can land. Resolve conflicts the same +way as before. + +```console +git fetch upstream +git rebase upstream/main +# fix any potential conflicts +git push -f origin 48-fix-http-agent-error +``` + +This will cause the pull request to be updated with your changes, and +CI will rerun. + +A maintainer may ask you to make changes to your pull request. Sometimes these +changes are minor and shouldn't appear in the commit log. For example, you may +have a typo in one of your code comments that should be fixed before merge. +You can prevent this from adding noise to the commit log with an interactive +rebase. See the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) +for details. + +```console +git commit -m "fixup: fix typo" +git rebase -i upstream/main # follow git instructions +``` + +Once you have rebased your commits, you can force push to your fork as before. + +## Congratulations! + +Congratulations! You've done it! We really appreciate the time and energy +you've given to the project. Thank you. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..b57fc6d --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,5 @@ +# Maintainers + +Current active maintainers of this SDK: + +- [John Laswell](https://github.com/jlaswell) diff --git a/README.md b/README.md index 35fae23..4428904 100644 --- a/README.md +++ b/README.md @@ -117,3 +117,10 @@ how SDK projects are for how PR reviews and approval, and our [Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md) information. + +## Additional SDK Resources + +- [List of current active maintainers](MAINTAINERS.md) +- [How to contribute to the project](CONTRIBUTING.md) +- [SDK's License](LICENSE) +- [SDK's Release process](RELEASING.md) diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..c20795f --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,3 @@ +To create a new release: +- Create a new Github release via the Github UI, making sure to prefix it + with `v`