From 847ed7a866030d379503817ad1e7a82f1fb61829 Mon Sep 17 00:00:00 2001 From: Matt Brictson Date: Fri, 26 Aug 2016 17:08:09 -0700 Subject: [PATCH] Reference the new documentation location (docs/) --- DEVELOPMENT.md | 8 +++++++- README.md | 3 +-- docs/README.md | 5 +++-- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 115a1cd5..36f02bc2 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,6 +1,7 @@ Thanks for helping build Capistrano! Here are the development practices followed by our community. * [Who can help](#who-can-help) +* [Contributing documentation](#contributing-documentation) * [Setting up your development environment](#setting-up-your-development-environment) * [Coding guidelines](#coding-guidelines) * [Submitting a pull request](#submitting-a-pull-request) @@ -17,6 +18,10 @@ Everyone can help improve Capistrano. There are ways to contribute even if you a * reviewing pull requests and suggesting improvements * reporting bugs or suggesting new features (see [CONTRIBUTING.md][]) +## Contributing documentation + +Improvements and additions to Capistrano's documentation are very much appreciated. The official documention is stored in the `docs/` directory as Markdown files. These files are used to automatically generate the [capistranorb.com](http://capistranorb.com/) website, which is hosted by GitHub Pages. Feel free to make changes to this documentation as you see fit. Before opening a pull request, make sure your documentation renders correctly by previewing the website in your local environment. Refer to [docs/README.md][] for instructions. + ## 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. @@ -71,7 +76,7 @@ Your code should conform to these guidelines: * 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` + * If you add a new feature, please make sure to document it by modifying the appropriate Markdown files in `docs/` (see [contributing documentation](#contributing-documentation), above). 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. @@ -120,3 +125,4 @@ After a pull request is merged, it is assigned to a GitHub milestone for the upc [CONTRIBUTING.md]: https://github.com/capistrano/capistrano/blob/master/CONTRIBUTING.md +[docs/README.md]: https://github.com/capistrano/capistrano/blob/master/docs/README.md diff --git a/README.md b/README.md index c0cbdcc3..7617a50c 100644 --- a/README.md +++ b/README.md @@ -173,7 +173,7 @@ $ bundle exec cap production deploy --print-config-variables Capistrano is a large project encompassing multiple GitHub repositories and a community of plugins, and it can be overwhelming when you are just getting started. Here are resources that can help: -* **[The Capistrano website](http://capistranorb.com) is the best place for official documentation** +* **The `docs/` directory contains the official documentation**, and is used to generate the [Capistrano website](http://capistranorb.com) * [Stack Overflow](http://stackoverflow.com/questions/tagged/capistrano) has a Capistrano tag with lots of activity * [The Capistrano mailing list](https://groups.google.com/forum/#!forum/capistrano) is low-traffic but is monitored by Capistrano contributors * [CodersClan](http://codersclan.net/?repo_id=325&source=link) has Capistrano experts available to solve problems for bounties @@ -181,7 +181,6 @@ Capistrano is a large project encompassing multiple GitHub repositories and a co Related GitHub repositories: * [capistrano/sshkit](https://github.com/capistrano/sshkit) provides the SSH behavior that underlies Capistrano (when you use `execute` in a Capistrano task, you are using SSHKit) -* [capistrano/documentation](https://github.com/capistrano/documentation) is what generates the official Capistrano website * [capistrano/rails](https://github.com/capistrano/rails) is a very popular gem that adds Ruby on Rails deployment tasks * [mattbrictson/airbrussh](https://github.com/mattbrictson/airbrussh) provides Capistrano's default log formatting diff --git a/docs/README.md b/docs/README.md index 96b428fa..f8ecd469 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,15 @@ # capistranorb.com -This is the repository that generates the [capistranorb.com](http://capistranorb.com/) site. Feel free to send pull requests to make improvements to Capistrano's documentation! +This `docs/` directory generates the [capistranorb.com](http://capistranorb.com/) site. Feel free to send pull requests to make improvements to Capistrano's documentation! ### Quick start This is a GitHub Pages project, which means it is built using Jekyll. To run the site locally, you'll need a functioning Ruby environment. -After checking out the capistrano-documentation project, run: +After checking out the capistrano repository, run: ``` +cd docs bundle install ```