chore: Document contribution and release processes

Author: dazuma

.github/CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # Contributing
 
-Want to contribute? Great! First, read this page (including the small print at the end).
+Want to contribute? Great! This page gives you the essentials you need to know.
 
-### Before you contribute
+## Before you contribute
 
 Before we can use your code, you must sign the
 [Google Individual Contributor License Agreement]
@@ -19,14 +19,96 @@ us first through the issue tracker with your idea so that we can help out and
 possibly guide you. Coordinating up front makes it much easier to avoid
 frustration later on.
 
-### Code reviews
+Contributions made by corporations are covered by a different agreement than
+the one above, the
+[Software Grant and Corporate Contributor License Agreement]
+(https://cla.developers.google.com/about/google-corporate).
+
+## Development
+
+### Useful tools
+
+The Functions Framework runs on Ruby 2.5 or later. We recommend having a recent
+version of Ruby for development and testing. The CI will test against all
+supported versions of Ruby.
+
+To run tests and other development processes, you should install the
+[Toys](https://github.com/dazuma/toys) gem, which provides the task runner and
+framework:
+
+    gem install toys
+
+You can then use Toys to run tests and other tasks. For example:
+
+    toys rubocop
+    toys test
+
+You can also run the entire suite of CI tests using:
+
+    toys ci
+
+Toys handles bundling for you; you do not need to `bundle exec` when running
+these tasks.
+
+Rake is not used by this repository.
+
+### Coding style
+
+When modifying code, please adhere to the existing coding style. This is
+enforced by Rubocop. See the [Rubocop config](.rubocop.yml) and the general
+Google Ruby style config at https://github.com/googleapis/ruby-style, which is
+based on "Seattle-style" Ruby.
+
+It's a good idea to run Rubocop locally to check style before opening a pull
+request:
+
+    toys rubocop
+
+### Tests
+
+All contributions should be accompanied by tests. You can run the tests with:
+
+    toys test
+
+Test files live in the `test` directory and must match `test_*.rb`. Tests
+_must_ use minitest as the test framework. This repository does not use rspec.
+Any common tooling can be put in the `helper.rb` file.
+
+We often use "spec-style" describe blocks rather than test classes, but we
+prefer assertion syntax over expectation syntax.
+
+The examples in the `examples` directory also have tests. These can be invoked
+by cd-ing into the relevant example directory and running `toys test`.
+
+Finally, this framework runs conformance tests that are defined in the
+https://github.com/GoogleCloudPlatform/functions-framework-conformance repo.
+To run the conformance tests:
+
+    toys conformance
+
+## Pull requests
 
 All submissions, including submissions by project members, require review. We
 use Github pull requests for this purpose.
 
-### The small print
+### Commit messages
 
-Contributions made by corporations are covered by a different agreement than
-the one above, the
-[Software Grant and Corporate Contributor License Agreement]
-(https://cla.developers.google.com/about/google-corporate).
+Commit messages _must_ follow
+[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) style.
+In short, you should prefix each commit message with a tag indicating the type
+of change, usually `feat:`, `fix:`, `docs:`, or `tests:`, `refactor:`, or
+`chore:`. The remainder of the commit message should be a description suitable
+for inclusion in release notes. For example:
+
+    fix: Fixed an error when setting a global to a Minitest::Mock
+
+or
+
+    feat: Support raw pubsub events sent by the pubsub emulator
+
+If your change is trivial and should not be listed in release notes or trigger
+a new release of the library, label it `chore:`.
+
+It is very important that commit messages follow this style, because the
+release tooling depends on it. If a commit message does not conform, the change
+will not be listed in the release notes and may not trigger a library release.

.rubocop.yml

@@ -7,6 +7,8 @@ AllCops:
     - "**/*.rb"
     - "**/Gemfile"
     - "*.gemspec"
+  Exclude:
+    - "examples/*/vendor/**/*.rb"
 
 Lint/ConstantDefinitionInBlock:
   Exclude:

RELEASING.md

@@ -0,0 +1,78 @@
+# Releasing
+
+Releases are performed using tooling developed by Google's GitHub Automation
+team, and are partially automated, but can be controlled by maintainers.
+
+## The automated release pipeline
+
+Whenever a commit is pushed to the main branch with a
+[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) message,
+the automated release pipeline will trigger.
+
+### Release pull requests
+
+The [release-please](https://github.com/googleapis/release-please) bot watches
+for commits that indicate a semantic change, normally either `feat:` or `fix:`,
+or any commit that includes a breaking change. When new commits are pushed,
+release-please will propose a new release whose version is based on the semver
+implication of the change: a patch release for a `fix:`, a minor release for a
+`feat:`, or a major release for a breaking change. This will appear in the form
+of a pull request, which will include the proposed new version, and a changelog
+entry.
+
+A maintainer can either:
+
+* Close the pull request to defer the release until more changes have been
+  committed.
+* Accept the release by merging the pull request, possibly after modifying the
+  changelog.
+
+Do NOT modify the version in the pull request. If you want to release a
+different version, see the next section on proposing releases manually.
+
+When merging a release pull request, make sure the `autorelease: pending` label
+remains applied. This is important for correct operation of the rest of the
+release pipeline.
+
+### Release scripts
+
+After a release pull request is merged, another bot will trigger the rest of
+the release pipeline. This bot runs every 15 minutes, so this process may be
+delayed a few minutes. Once it runs, it will do the following automatically:
+
+* Tag the release and create a GitHub release. This takes place in a kokoro
+  (internal Google) job. Once finished, it will switch the tag from
+  `autorelease: pending` to `autorelease: tagged`. If it seems to be
+  malfunctioning, you can find logs on the internal fusion dashboard under the
+  job `cloud-devrel/client-libraries/autorelease/tag`.
+* Build and push the gem to Rubygems, and build and push the documentation to
+  googleapis.dev. This takes place in a second kokoro job. Once finished, it
+  will switch the tag from `autorelease: tagged` to `autorelease: published`.
+  If this job seems to be malfunctioning, find the logs under the kokoro job
+  `cloud-devrel/ruby/functions-framework-ruby/release`.
+
+## Manually proposing a release
+
+If you want to propose a release out-of-band or customize the version number to
+use, you can use a command line tool to create a release pull request.
+
+### Prerequisites
+
+You need to install:
+
+* git version 2.22 or later
+* The gh cli (https://cli.github.com/)
+* The release-please npm module
+* The toys rubygem
+
+### Running the release proposal script
+
+Once the prerequisites are installed, run:
+
+    toys release please functions_framework:1.2.3
+
+(Replace `1.2.3` with the version to release.)
+
+This will open an appropriate release pull request. Then you can merge it
+(possibly after modifying the changelog) and the release pipeline will proceed
+as described above.