diff --git a/.yardopts b/.yardopts index 334db25..8dd7f09 100644 --- a/.yardopts +++ b/.yardopts @@ -8,4 +8,4 @@ - README.md CHANGELOG.md -LICENSE.md +LICENSE diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fa6722c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,167 @@ +# Contributing to CloudEvents' Ruby 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-ruby.git +cd sdk-ruby +git remote add upstream https://github.com/cloudevents/sdk-ruby.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/LICENSE.md b/LICENSE similarity index 100% rename from LICENSE.md rename to LICENSE diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..dbf257d --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,5 @@ +# Maintainers + +Current active maintainers of this SDK: + +- [Daniel Azuma](https://github.com/dazuma) diff --git a/README.md b/README.md index b7cfaf1..77f3553 100644 --- a/README.md +++ b/README.md @@ -184,31 +184,6 @@ few things to keep in mind. * **Make sure CI passes.** Invoke `toys ci` to run the tests locally before opening a pull request. This will include code style checks. -### Releasing - -Releases can be performed only by users with write access to the repository. - -To perform a release: - - 1. Go to the GitHub Actions tab, and launch the "Request Release" workflow. - You can leave the input field blank. - - 2. The workflow will analyze the commit messages since the last release, and - open a pull request with a new version and a changelog entry. You can - optionally edit this pull request to modify the changelog or change the - version released. - - 3. Merge the pull request (keeping the `release: pending` label set.) Once the - CI tests have run successfully, a job will run automatically to perform the - release, including tagging the commit in git, building and releasing a gem, - and building and pushing documentation. - -These tasks can also be performed manually by running the appropriate scripts -locally. See `toys release request --help` and `toys release perform --help` -for more information. - -If a release fails, you may need to delete the release tag before retrying. - ### For more information * Library documentation: https://cloudevents.github.io/sdk-ruby @@ -243,18 +218,9 @@ for how PR reviews and approval, and our [Code of Conduct](https://github.com/cloudevents/spec/blob/master/community/GOVERNANCE.md#additional-information) information. -## Licensing - - Copyright 2020 Google LLC and the CloudEvents Ruby SDK Contributors - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this software except in compliance with the License. - You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 +## Additional SDK Resources - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +- [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..de182ae --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,25 @@ +# Releasing + +Releases can be performed only by users with write access to the repository. + +To perform a release: + + 1. Go to the GitHub Actions tab, and launch the "Request Release" workflow. + You can leave the input field blank. + + 2. The workflow will analyze the commit messages since the last release, and + open a pull request with a new version and a changelog entry. You can + optionally edit this pull request to modify the changelog or change the + version released. + + 3. Merge the pull request (keeping the `release: pending` label set.) Once the + CI tests have run successfully, a job will run automatically to perform the + release, including tagging the commit in git, building and releasing a gem, + and building and pushing documentation. + +These tasks can also be performed manually by running the appropriate scripts +locally. See `toys release request --help` and `toys release perform --help` +for more information. + +If a release fails, you may need to delete the release tag before retrying. +