b5e4aa6d5e
This adds various "doctor" tasks that can be used for troubleshooting. To see
all the doctor output, run e.g. `cap production doctor`. This will print a
report like this:
```
Environment
Ruby ruby 2.3.0p0 (2015-12-25 revision 53290) [x86_64-darwin14]
Rubygems 2.6.2
Bundler 1.11.2
Command cap production doctor
Gems
capistrano 3.4.0
airbrussh 1.0.1
rake 10.5.0 (update available)
sshkit 1.9.0
capistrano-bundler 1.1.4
capistrano-rails 1.1.6
Variables
:application "myapp"
:assets_prefix "assets"
:assets_roles [:web]
:branch "master"
... etc.
```
To obtain the variables information in particular, code has been added to audit
the setting and fetching of variables. Variables set by Capistrano itself and
its plugins are whitelisted, but others are "untrusted". If a variable is
untrusted and it seems like it is never used, then `doctor:variables` will print
a warning (include source location) for that variable name, like this:
```
:copy_strategy is not a recognized Capistrano setting (config/deploy.rb:14)
```
Finally, the RubyGems API is used to check the remote gem repository to see if
any newer versions of Capistrano gems are available (this is gracefully skipped
if there is no network connection). Any outdated gems will be indicated in the
`doctor:gems` output.
3.3 KiB
Hello and welcome! Please look over this document before opening an issue or submitting a pull request to Capistrano.
- If you’re looking for help or have a question
- Reporting bugs
- Requesting new features or improvements
- Contributing code or documentation
If you’re looking for help or have a question
Check Stack Overflow 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.)
If you have an urgent problem you can also try CodersClan, which has a community of Capistrano experts dedicated to solve code problems for bounties.
When posting to Stack Overflow or CodersClan, be sure to include relevant information:
- Capistrano version
- Plugins and versions (capistrano-rvm, capistrano-bundler, etc.)
- Logs and backtraces
If you think you’ve found a bug in Capistrano itself, then…
Reporting bugs
As much the Capistrano community tries to write good, well-tested code, bugs still happen. Sorry about that!
In case you’ve run across an already-known issue, check the FAQs first on the official Capistrano site.
When opening a bug report, please include the output of the cap <stage> doctor task, e.g.:
cap production doctor
Also include in your report:
- Versions of Ruby, Capistrano, and any plugins you’re using (if
doctordidn't already do this for you) - A description of the troubleshooting steps you’ve taken
- Logs and backtraces
- Sections of your
deploy.rbthat may be relevant - Any other unique aspects of your environment
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!
Requesting new features or improvements
Capistrano continues to improve thanks to people like you! Feel free to open a GitHub issue for any or all of these ideas:
- New features that would make Capistrano even better
- Areas where documentation could be improved
- Ways to improve developer happiness
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.