mirror of
https://github.com/capistrano/capistrano
synced 2023-03-27 23:21:18 -04:00
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.
61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
**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](#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’re looking for help or have a question
|
||
|
||
**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.)
|
||
|
||
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.
|
||
|
||
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](http://capistranorb.com).**
|
||
|
||
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 `doctor` didn't already do this for you)
|
||
* 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
|
||
|
||
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][].
|
||
|
||
|
||
[DEVELOPMENT.md]: https://github.com/capistrano/capistrano/blob/master/DEVELOPMENT.md
|