diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e722cc5f3..6e1c8046e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,8 @@ -Want to contribute? Great! First, read this page (including the small print at the end). +Want to contribute? Great! First, read this page (including the small print at +the end). ### Before you contribute + Before we can use your code, you must sign the [Google Individual Contributor License Agreement](https://developers.google.com/open-source/cla/individual?csw=1) (CLA), which you can do online. The CLA is necessary mainly because you own the @@ -16,86 +18,108 @@ possibly guide you. Coordinating up front makes it much easier to avoid frustration later on. ### Code reviews + All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. -### The small print -Contributions made by corporations are covered by a different agreement than -the one above, the Software Grant and Corporate Contributor License Agreement. +### Configuring a local development environment -### Change log -After creating a pull request, update the appropriate sections in CHANGES.next.md with a summary of your changes, then commit and push to the branch you are trying to merge. +Reference the setup section in the [README](README.md#installation-and-setup) or +the [beginner tutorial](tutorials/beginner_walkthrough/README.md) for an example +of how to setup a local development environment. -For example, under "Bug fixes and maintenance updates" you might put something like: -``` -- Fix crazy bug X (GH- from @) -``` +### Fork the repository -Then: -``` -git commit -m "Updated CHANGES.next.md" -git push origin fix_crazy_bug_x -``` +If you plan on contributing, create your own fork of PerfKitBenchmarker to +publish your changes. GitHub has +[a great tutorial](https://help.github.com/articles/fork-a-repo/) (we follow the +*Fork & pull* model). -### Configuring a local development environment -This can optionally done within a [`virtualenv`](https://virtualenv.pypa.io/en/latest/). +1. Fork the repository: -### Fork the repository + ``` + gh repo fork GoogleCloudPlatform/PerfKitBenchmarker + ``` + +2. Clone the repository: + + ``` + cd $HOME && git clone https://github.com/{github_username}/PerfKitBenchmarker + ``` + + ``` + cd PerfKitBenchmarker/ + ``` + +3. Install Python 3 and pip (activate virtualenvs if needed). + +4. Install PerfKitBenchmarker's Python dependencies: + + ``` + pip install -r requirements.txt + ``` + +5. Install PerfKitBenchmarker's test dependencies: -If you plan on contributing, create your own fork of PerfKitBenchmarker to publish your changes. -GitHub has [a great tutorial](https://help.github.com/articles/fork-a-repo/) (we follow the *Fork & pull* model). - -- Clone the repository: -``` -$ git clone git@github.com:/PerfKitBenchmarker.git && cd PerfKitBenchmarker -``` -- Install Python 2.7. -- Install [pip](https://pypi.python.org/pypi/pip): -``` -$ sudo apt-get install -y python-pip -``` -- Install PerfKitBenchmarker's Python dependencies: -``` -$ [sudo] pip install -r requirements.txt -``` -- Install PerfKitBenchmarker's test dependencies: -``` -$ [sudo] pip install tox -``` -- Install git pre-commit hooks, to enable linting and copyright checks: -``` -$ hooks/install.sh -``` + ``` + pip install -r requirements-testing.txt + ``` ### Create a branch -Start from the master branch of the repository. This is the default. - -- Create a branch to contain your changes. -``` -$ git checkout -b -``` - -- Make your modifications to the code in one or more commits [(guidelines for useful git commit messages)](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). -- Push your changes to GitHub -``` -$ git push origin -``` -- Create a pull request to integrate your change into the `master` branch. -This can be done on github.com, or by installing and using the command line tool [`hub`](https://github.com/github/hub). -``` -$ hub pull-request -h -``` -When making a pull request on GitHub, please the base branch of the Pull Request should be `master`. This is usually the default. +Start from the master branch of the repository. This is the default. + +1. Create a branch to contain your changes. + + ``` + git checkout -b + ``` + +2. Make your modifications to the code in one or more commits + [(guidelines for useful git commit messages)](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). + +3. Update the appropriate sections in CHANGES.next.md with a summary of your + changes. For example, under "Bug fixes and maintenance updates" you might + put something like: `- Fix crazy bug X (GH- from + @)` + +4. Push your changes to GitHub + + ``` + git push origin + ``` + +5. Create a pull request to integrate your change into the `master` branch. + This can be done on github.com, or through CLIs. See GitHub's documentation + [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) + for more details. When making a pull request on GitHub, the base branch of + the Pull Request should be `master`. This is usually the default. ### Developer documentation + We have added a lot of comments into the code to make it easy to; -* Add new benchmarks (eg: --benchmarks=) -* Add new package/os type support (eg: --os_type=) -* Add new providers (eg: --cloud=) -* etc... -Even with lots of comments we make to support more detailed documention. You will find the documatation we have on the [Wiki pages] (https://github.com/GoogleCloudPlatform/PerfKitBenchmarker/wiki). Missing documentation you want? Start a page and/or open an [issue] (https://github.com/GoogleCloudPlatform/PerfKitBenchmarker/issues) to get it added. +* Add new benchmarks (eg: --benchmarks=) +* Add new package/os type support (eg: --os_type=) +* Add new providers (eg: --cloud=) +* etc... + +Even with lots of comments we make to support more detailed documentation. You +will find the documentation we have on the +[Wiki pages](https://github.com/GoogleCloudPlatform/PerfKitBenchmarker/wiki). +Missing documentation you want? Start a page and/or open an +[issue](https://github.com/GoogleCloudPlatform/PerfKitBenchmarker/issues) to get +it added. ### Updating the GitHub Pages site: -The site requires [Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll) in order to run. Use `bundle install` and `bundle install` to update the dependencies in `Gemfile.lock`. + +The site requires +[Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll) +in order to run. Use `bundle install` and `bundle update` to update the +dependencies in `Gemfile.lock`. `bundle exec jekyll serve` can be used to test +the site locally. + +### The small print + +Contributions made by corporations are covered by a different agreement than the +one above, the Software Grant and Corporate Contributor License Agreement. ~~~