mirror of
https://github.com/capistrano/capistrano
synced 2023-03-27 23:21:18 -04:00
Document project workflow and contrib guidelines
This commit is contained in:
Matt Brictson
parent
41179c408e
commit
60e4d805b8
3 changed files with 168 additions and 76 deletions
114
CONTRIBUTING.md
114
CONTRIBUTING.md
|
|
@ -1,93 +1,55 @@
|
|||
## CONTRIBUTING
|
||||
**Hello and welcome!** Please look over this document before opening an issue or submitting a pull request to Capistrano.
|
||||
|
||||
**The issue tracker is intended exclusively for things that are genuine bugs,
|
||||
or improvements to the code.**
|
||||
* [If you’re looking for help or have a question](#if-youre-looking-for-help-or-have-a-question)
|
||||
* [Reporting bugs](#reporting-bugs)
|
||||
* [Requesting new features or improvements](#requesting-new-features-or-improvements)
|
||||
* [Contributing code or documentation](#contributing-code-or-documentation)
|
||||
|
||||
If you have a user support query, or you suspect that you might just be holding
|
||||
it wrong, drop us a line at [the mailing list](https://groups.google.com/forum/#!forum/capistrano), [StackOverflow](http://stackoverflow.com/questions/tagged/capistrano) or at [CodersClan](http://codersclan.net/?repo_id=325&source=contributing). The
|
||||
mailing list is moderated to cut down on spam, so please be patient, if you use
|
||||
StackOverflow, make sure to tag your post with "Capistrano". (Not forgetting
|
||||
any other tags which might relate, rvm, rbenv, Ubuntu, etc.)
|
||||
## If you’re looking for help or have a question
|
||||
|
||||
If you have an urgent problem you can use [CodersClan](http://codersclan.net/?repo_id=325&source=contributing) to solve your problem quickly. CodersClan has a community of Capistrano experts dedicated to solve code problems for bounties.
|
||||
**Check [Stack Overflow](http://stackoverflow.com/questions/tagged/capistrano) first if you need help using Capistrano.** You are more likely to get a quick response at Stack Overflow for common Capistrano topics. Make sure to tag your post with `capistrano` and/or `capistrano3` (not forgetting any other tags which might relate: rvm, rbenv, Ubuntu, etc.)
|
||||
|
||||
Wherever you post please be sure to include the version of Capistrano you are
|
||||
using, which versions of any plugins (*capistrano-rvm*, *capistrano-bundler*,
|
||||
etc.). Proper logs are vital, if you need to redact them, go ahead, but be
|
||||
careful not to remove anything important. Please take care to format logs and
|
||||
code correctly, ideally wrapped to a sane line length, and in a mono spaced
|
||||
font. This all helps us to gather a clear understanding of what is going wrong.
|
||||
If you have an urgent problem you can also try [CodersClan](http://codersclan.net/?repo_id=325&source=contributing), which has a community of Capistrano experts dedicated to solve code problems for bounties.
|
||||
|
||||
**If you really think that you found a bug, or want to enquire about a feature,
|
||||
or send us a patch to add a feature, or fix a bug, please keep a few things in
|
||||
mind:**
|
||||
When posting to Stack Overflow or CodersClan, be sure to include relevant information:
|
||||
|
||||
## When Submitting An Issue:
|
||||
* Capistrano version
|
||||
* Plugins and versions (capistrano-rvm, capistrano-bundler, etc.)
|
||||
* Logs and backtraces
|
||||
|
||||
If you think there's a bug, please make sure it's really a bug in Capistrano.
|
||||
As Capistrano sits on the (sometimes rough) edges between SSH, Git, the
|
||||
network, Ruby, RVM, rbenv, chruby, Bundler, your Linux distribution, countless
|
||||
shell configuration files on your end, and the server… there's a good chance
|
||||
the problem lies somewhere else.
|
||||
If you think you’ve found a bug in Capistrano itself, then…
|
||||
|
||||
Please make sure you have reviewed the FAQs at http://www.capistranorb.com/.
|
||||
## Reporting bugs
|
||||
|
||||
It's really important to include as much information as possible, versions of
|
||||
everything involved, anything weird you might be doing that might be having
|
||||
side effects, include as much as you can in a [GitHub
|
||||
Gist](https://gist.github.com/) and link that from the issue, with tools such
|
||||
as Gist, we can link to individual lines and help work out what is going wrong.
|
||||
As much the Capistrano community tries to write good, well-tested code, bugs still happen. Sorry about that!
|
||||
|
||||
If you are an experienced Ruby programmer, take a few minutes to get our test
|
||||
suite running, and do what you can to get a test case written that fails, from
|
||||
there we can understand exactly what it takes to reproduce the issue (as it's
|
||||
documented with code)
|
||||
**In case you’ve run across an already-known issue, check the FAQs first on the [official Capistrano site](http://capistranorb.com).**
|
||||
|
||||
## When Requesting a Feature:
|
||||
When opening a bug report, please include the following:
|
||||
|
||||
We can't make everyone happy all of the time, and we've been around the block
|
||||
well enough to know when something doesn't work well, or when your proposed fix
|
||||
might impact other things.
|
||||
* Versions of Ruby, Capistrano, and any plugins you’re using
|
||||
* A description of the troubleshooting steps you’ve taken
|
||||
* Logs and backtraces
|
||||
* Sections of your `deploy.rb` that may be relevant
|
||||
* Any other unique aspects of your environment
|
||||
|
||||
We prefer to [start with
|
||||
"no"](https://gettingreal.37signals.com/ch05_Start_With_No.php), and help you
|
||||
find a better way to solve your problem, sometimes the solution is to [build
|
||||
faster
|
||||
horses](http://blog.cauvin.org/2010/07/henry-fords-faster-horse-quote.html),
|
||||
sometimes the solution is to work around it in a neat way that you didn't know
|
||||
existed.
|
||||
If you are an experienced Ruby programmer, take a few minutes to get the Capistrano test suite running (see [DEVELOPMENT.md][]), and do what you can to get a test case written that fails. *This will be a huge help!*
|
||||
|
||||
Please don't be offended if we say no, and don't be afraid to fight your
|
||||
corner, try and avoid being one of the [poisonous
|
||||
people](https://www.youtube.com/watch?v=Q52kFL8zVoM)
|
||||
## Requesting new features or improvements
|
||||
|
||||
## Submitting A Pull Request:
|
||||
Capistrano continues to improve thanks to people like you! Feel free to open a GitHub issue for any or all of these ideas:
|
||||
|
||||
Pull requests are awesome, and if they arrive with decent tests, and conform to
|
||||
the guidelines below, we'll merge them in as soon as possible, we'll let you
|
||||
know which release we're planning them for (we adhere to
|
||||
[semver](http://semver.org/) so please don't be upset if we plan your changes
|
||||
for a later release)
|
||||
* New features that would make Capistrano even better
|
||||
* Areas where documentation could be improved
|
||||
* Ways to improve developer happiness
|
||||
|
||||
* The code is MIT licenced, your code will fall under the same license if we merge it.
|
||||
* We can't merge it without a [good commit
|
||||
message](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message).
|
||||
If you do this right, Github will use the commit message as the body of your
|
||||
pull request, double win.
|
||||
* If you are referencing an improvement to an existing issue (if we have not
|
||||
yet merged it )
|
||||
* Add an entry to the `CHANGELOG` under the `### master` section, but please
|
||||
don't mess with the version.
|
||||
* If you add a new feature, please make sure to document it, open a
|
||||
corresponding pull request in [the
|
||||
documentation](https://github.com/capistrano/documentation) and mention the
|
||||
code change pull request over there, and Github will link everything up. If
|
||||
it's a simple feature, or a new variable, or something changed, it may be
|
||||
appropriate simply to document it in the generated `Capfile` or `deploy.rb`, or
|
||||
in the `README`
|
||||
* Take care to squash your commit into one single commit with a good message, it
|
||||
saves us a lot of work in maintaining the CHANGELOG if we can generate it from
|
||||
the commit messages between the release tags!
|
||||
* Tests! It's tricky to test some parts of Capistrano, but do your best, it
|
||||
might just serve as a starting point for us to build a reliable test on top of,
|
||||
and help us understand where you are coming from.
|
||||
Generally speaking the maintainers are very conservative about adding new features, and we can’t guarantee that the community will agree with or implement your idea. Please don’t be offended if we say no! The Capistrano team will do our best to review all suggestions and at least weigh in with a comment or suggest a workaround, if applicable.
|
||||
|
||||
**Your idea will have a much better chance of becoming reality if you contribute code for it (even if the code is incomplete!).**
|
||||
|
||||
## Contributing code or documentation
|
||||
|
||||
So you want to contribute to Capistrano? Awesome! We have a whole separate document just you. It explains our pull request workflow and walks you through setting up the development environment: [DEVELOPMENT.md][].
|
||||
|
||||
|
||||
[DEVELOPMENT.md]: https://github.com/capistrano/capistrano/blob/master/DEVELOPMENT.md
|
||||
|
|
|
|||
114
DEVELOPMENT.md
Normal file
114
DEVELOPMENT.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
Thanks for helping build Capistrano! Here are the development practices followed by our community.
|
||||
|
||||
* [Who can help](#who-can-help)
|
||||
* [Setting up your development environment](#setting-up-your-development-environment)
|
||||
* [Submitting a pull request](#submitting-a-pull-request)
|
||||
* [Managing GitHub issues](#managing-github-issues)
|
||||
* [Reviewing and merging pull requests](#reviewing-and-merging-pull-requests)
|
||||
|
||||
## Who can help
|
||||
|
||||
Everyone can help improve Capistrano. There are ways to contribute even if you aren’t a Ruby programmer. Here’s what you can do to help the project:
|
||||
|
||||
* adding to or fixing typos/quality in documentation
|
||||
* adding failing tests for reported bugs
|
||||
* writing code (no contribution is too small!)
|
||||
* reviewing pull requests and suggesting improvements
|
||||
* reporting bugs or suggesting new features (see [CONTRIBUTING.md][])
|
||||
|
||||
## Setting up your development environment
|
||||
|
||||
Capistrano is a Ruby project, so we expect you to have a functioning Ruby environment. To hack on Capistrano you will further need some specialized tools to run its test suite.
|
||||
|
||||
Make sure to install:
|
||||
|
||||
* [Bundler](https://bundler.io/) 1.10.5 (see note)
|
||||
* [Vagrant](https://www.vagrantup.com/)
|
||||
* [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (or another [Vagrant-supported](https://docs.vagrantup.com/v2/getting-started/providers.html) VM host)
|
||||
|
||||
*Note: As of this writing (December 2015), Vagrant does not work with Bundler > 1.10.5. If you have multiple versions of Bundler installed, use the special underscore command-line argument to force a compatible version, like this: `bundle _1.10.5_ exec rake features`.*
|
||||
|
||||
### Running tests
|
||||
|
||||
Capistrano has two test suites: an RSpec suite and a Cucumber suite. The RSpec suite handles quick feedback unit specs. The Cucumber suite is an integration suite that uses Vagrant to deploy to a real virtual server.
|
||||
|
||||
```
|
||||
# Ensure all dependencies are installed
|
||||
$ bundle install
|
||||
|
||||
# Run the RSpec suite
|
||||
$ bundle exec rake spec
|
||||
|
||||
# Run the Cucumber suite (requires Bundler 1.10.5)
|
||||
$ bundle exec rake features
|
||||
|
||||
# Run the Cucumber suite and leave the VM running (faster for subsequent runs)
|
||||
$ bundle exec rake features KEEP_RUNNING=1
|
||||
```
|
||||
|
||||
### Report failing Cucumber features!
|
||||
|
||||
Currently, the Capistrano Travis build does *not* run the Cucumber suite. This means it is possible for a failing Cucumber feature to sneak in without being noticed by our continuous integration checks.
|
||||
|
||||
**If you come across a failing Cucumber feature, this is a bug.** Please report it by opening a GitHub issue. Or even better: do your best to fix the feature and submit a pull request!
|
||||
|
||||
|
||||
## Submitting a pull request
|
||||
|
||||
Pull requests are awesome, and if they arrive with decent tests, and conform to the guidelines below, we'll merge them in as soon as possible, we'll let you know which release we're planning them for (we adhere to [semver](http://semver.org/) so please don't be upset if we plan your changes for a later release).
|
||||
|
||||
Your code should conform to these guidelines:
|
||||
|
||||
* The code is MIT licenced, your code will fall under the same license if we merge it.
|
||||
* We can't merge it without a [good commit message](http://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message). If you do this right, Github will use the commit message as the body of your pull request, double win.
|
||||
* If you are making an improvement/fix for an existing issue, make sure to mention the issue number (if we have not yet merged it )
|
||||
* Add an entry to the `CHANGELOG` under the `### master` section, but please don't mess with the version.
|
||||
* If you add a new feature, please make sure to document it, open a corresponding pull request in [the documentation](https://github.com/capistrano/documentation) and mention the code change pull request over there, and Github will link everything up. If it's a simple feature, or a new variable, or something changed, it may be appropriate simply to document it in the generated `Capfile` or `deploy.rb`, or in the `README`
|
||||
* Take care to squash your commit into one single commit with a good message, it saves us a lot of work in maintaining the CHANGELOG if we can generate it from the commit messages between the release tags!
|
||||
* Tests! It's tricky to test some parts of Capistrano, but do your best, it might just serve as a starting point for us to build a reliable test on top of, and help us understand where you are coming from.
|
||||
|
||||
## Managing GitHub issues
|
||||
|
||||
The Capistrano maintainers will do our best to review all GitHub issues. Here’s how we manage issues:
|
||||
|
||||
1. Issues will be acknowledged with an appropriate label (see below).
|
||||
2. Issues that are duplicates, spam, or irrelevant (e.g. wrong project), or are questions better suited for Stack Overflow (see [CONTRIBUTING.md][]) will be closed.
|
||||
3. Once an issue is fixed or resolved in an upcoming Capistrano release, it will be closed and assigned to a GitHub milestone for that upcoming version number.
|
||||
|
||||
The maintainers do not have time to fix every issue ourselves, but we will gladly accept pull requests, especially for issues labeled as "you can help" (see below).
|
||||
|
||||
### Issue labels
|
||||
|
||||
Capistrano uses these GitHub labels to categorize issues:
|
||||
|
||||
* **bug?** – Could be a bug (not reproducible or might be user error)
|
||||
* **confirmed bug** – Definitely a bug
|
||||
* **new feature** – A request for Capistrano to add a feature or work differently
|
||||
* **chore** – A TODO that is neither a bug nor a feature (e.g. improve docs, CI infrastructure, etc.)
|
||||
|
||||
Also, the Capistrano team will sometimes add these labels to facilitate communication and encourage community feedback:
|
||||
|
||||
* **discuss!** – The Capistrano team wants more feedback from the community on this issue; e.g. how a new feature should work, or whether a bug is serious or not.
|
||||
* **you can help!** – We want the community to help by submitting a pull request to solve a bug or add a feature. If you are looking for ways to contribute to Capistrano, start here!
|
||||
* **needs more info** – We need more info from the person who opened the issue; e.g. steps to reproduce a bug, clarification on a desired feature, etc.
|
||||
|
||||
*These labels were inspired by Daniel Doubrovkine’s [2014 Golden Gate Ruby Conference talk](http://confreaks.tv/videos/gogaruco2014-taking-over-someone-else-s-open-source-projects).*
|
||||
|
||||
## Reviewing and merging pull requests
|
||||
|
||||
Pull requests and issues follow similar workflows. Before merging a pull request, the Capistrano maintainers will check that these requirements are met:
|
||||
|
||||
* All CI checks pass
|
||||
* Significant changes in behavior or fixes mentioned in the CHANGELOG
|
||||
* Clean commit history
|
||||
* New features are documented
|
||||
* Code changes/additions are tested
|
||||
|
||||
If any of these are missing, the **needs more info** label is assigned to the pull request to indicate the PR is incomplete.
|
||||
|
||||
Merging a pull request is a decision entrusted to the maintainers of the Capistrano project. Any maintainer is free to merge a pull request if they feel the PR meets the above requirements and is in the best interest of the Capistrano community.
|
||||
|
||||
After a pull request is merged, it is assigned to a GitHub milestone for the upcoming version number.
|
||||
|
||||
|
||||
[CONTRIBUTING.md]: https://github.com/capistrano/capistrano/blob/master/CONTRIBUTING.md
|
||||
16
RELEASING.md
Normal file
16
RELEASING.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
# Releasing
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* You must have commit rights to the Capistrano repository.
|
||||
* You must have push rights for the capistrano gem on rubygems.org.
|
||||
|
||||
## How to release
|
||||
|
||||
1. Run `bundle install` to make sure that you have all the gems necessary for testing and releasing.
|
||||
2. **Ensure all tests are passing by running `rake spec` and `rake features`.**
|
||||
3. Determine which would be the correct next version number according to [semver](http://semver.org/).
|
||||
4. Update the version in `./lib/capistrano/version.rb`.
|
||||
5. Update the `CHANGELOG`.
|
||||
6. Commit the changelog and version in a single commit, the message should be "Preparing vX.Y.Z"
|
||||
7. Run `rake release`; this will tag, push to GitHub, and publish to rubygems.org.
|
||||
Loading…
Reference in a new issue