Unify RubyGems and Bundler documentation

CONTRIBUTING.md

@@ -1,9 +1,71 @@
-# How to contribute
+# How to Contribute
 
-## Contributing to RubyGems
+Thank you for your interest in contributing to RubyGems and Bundler! Community involvement is essential to both RubyGems and Bundler. We welcome contributions from everyone, and we want to keep it as easy as possible to contribute changes.
 
-Check [RubyGems contribution guidelines](doc/rubygems/CONTRIBUTING.md).
+## Code of Conduct
 
-## Contributing to Bundler
+By participating in this project, you agree to abide by the terms of the [Code of Conduct](CODE_OF_CONDUCT.md).
 
-Check [Bundler contribution guidelines](doc/bundler/contributing/README.md).
+## Getting Started
+
+Before submitting a contribution:
+
+1. **Set up your development environment** - See [GETTING_STARTED.md](doc/GETTING_STARTED.md) for detailed setup instructions
+2. **Understand the repository structure** - This is a monorepo containing both RubyGems and Bundler:
+   - RubyGems code is in the root `lib/` and `exe/` directories
+   - Bundler code is in the `bundler/` subdirectory
+
+## Contribution Guidelines
+
+All contributions to this repository should follow these guidelines:
+
+1. **Write tests** - New features must be coupled with tests. Bug fixes should include a test that reproduces the issue.
+
+2. **Code style compliance**:
+   - No trailing whitespace
+   - Use two-space indentation
+   - Run `bin/rake rubocop` to check style compliance
+
+3. **File management** (RubyGems only):
+   - If you add or remove files in the RubyGems portion of the repo, update `Manifest.txt` by running `bin/rake update_manifest`
+
+4. **Preserve version history**:
+   - Don't modify version numbers or changelog files directly; maintainers handle these
+
+5. **Ask questions** - Have questions? Feel free to [open an issue](https://github.com/ruby/rubygems/issues)
+
+For more information on contributing to the RubyGems ecosystem, see [guides.rubygems.org/contributing](https://guides.rubygems.org/contributing/).
+
+## First-Time Contributors
+
+We track [good first issues](https://github.com/ruby/rubygems/issues?q=is%3Aissue+is%3Aopen+label%3Abundler+label%3A%22good+first+issue%22) to help new contributors get started. Here are some great ways to begin:
+
+- **Test prerelease versions**: Run `gem install bundler --pre` and report any issues
+- **Report bugs or suggest features**: [Open an issue](https://github.com/ruby/rubygems/issues/new?labels=Bundler&template=bundler-related-issue.md) (see [new features documentation](doc/NEW_FEATURES.md))
+- **Improve documentation**: Contribute to the [Bundler website](https://bundler.io) or [man pages](https://bundler.io/man/bundle.1.html)
+- **Triage issues**: [Check issue completeness](doc/ISSUE_TRIAGE.md) and help close incomplete reports
+- **Write tests**: Add failing tests for [reported bugs](https://github.com/ruby/rubygems/issues) or backfill missing test coverage
+- **Review pull requests**: Provide feedback on [pull requests](https://github.com/ruby/rubygems/pulls)
+- **Improve code**: No patch is too small—fix typos, improve code clarity, or clean up whitespace
+- **Contribute features**: See [adding new features](doc/NEW_FEATURES.md)
+
+## Pull Request Guidelines
+
+See [doc/PULL_REQUESTS.md](doc/PULL_REQUESTS.md) for detailed guidelines.
+
+## Community and Support
+
+Community involvement is vital to both projects:
+
+- **Answer questions**: Help others on the [issue tracker](https://github.com/ruby/rubygems/issues) or [Stack Overflow](https://stackoverflow.com/questions/tagged/bundler) (questions about RubyGems, Bundler, and Ruby in general are welcome)
+- **Share knowledge**: Write blog posts, create examples, make videos, or share your experiences
+- **Improve documentation**: Suggest improvements to [bundler.io](https://bundler.io) via issues or pull requests on the [bundler-site](https://github.com/rubygems/bundler-site) repository
+
+## Supporting the Projects
+
+Both RubyGems and Bundler are managed by [Ruby Central](https://rubycentral.org), a non-profit organization supporting the Ruby community through projects like these, as well as [RubyConf](https://rubyconf.org) and [RubyGems.org](https://rubygems.org).
+
+You can support Ruby Central by:
+
+- Attending or [sponsoring](mailto:sponsors@rubycentral.org) a conference
+- [Joining as a supporting member](https://rubycentral.org/#/portal/signup)

Manifest.txt

@@ -352,9 +352,8 @@ bundler/lib/bundler/vlad.rb
 bundler/lib/bundler/worker.rb
 bundler/lib/bundler/yaml_serializer.rb
 doc/MAINTAINERS.txt
+doc/POLICIES.md
 doc/UPGRADING.md
-doc/rubygems/CONTRIBUTING.md
-doc/rubygems/POLICIES.md
 exe/gem
 exe/update_rubygems
 hide_lib_for_update/note.txt

Rakefile

@@ -93,10 +93,9 @@ RDoc::Task.new rdoc: "docs", clobber_rdoc: "clobber_docs" do |doc|
   doc.title  = "RubyGems #{v} API Documentation"
 
   rdoc_files = Rake::FileList.new %w[lib bundler/lib]
-  rdoc_files.add %w[CHANGELOG.md LICENSE.txt MIT.txt CODE_OF_CONDUCT.md doc/rubygems/CONTRIBUTING.md
-                    doc/MAINTAINERS.txt Manifest.txt doc/rubygems/POLICIES.md README.md doc/UPGRADING.md bundler/CHANGELOG.md
-                    doc/bundler/contributing/README.md bundler/LICENSE.md bundler/README.md
-                    hide_lib_for_update/note.txt].map(&:freeze)
+  rdoc_files.add %w[CHANGELOG.md LICENSE.txt MIT.txt CODE_OF_CONDUCT.md CONTRIBUTING.md
+                    doc/MAINTAINERS.txt Manifest.txt doc/POLICIES.md README.md doc/UPGRADING.md bundler/CHANGELOG.md
+                    bundler/LICENSE.md bundler/README.md hide_lib_for_update/note.txt].map(&:freeze)
 
   doc.rdoc_files = rdoc_files
 
@@ -485,8 +484,7 @@ module Rubygems
       %w[
         doc/MAINTAINERS.txt
         doc/UPGRADING.md
-        doc/rubygems/CONTRIBUTING.md
-        doc/rubygems/POLICIES.md
+        doc/POLICIES.md
       ].each {|f| files << f }
 
       files.sort

bundler/README.md

@@ -27,23 +27,15 @@ bundle exec rspec
 
 See [bundler.io](https://bundler.io) for the full documentation.
 
-## Troubleshooting
+## Getting help
 
-For help with common problems, see [TROUBLESHOOTING](../doc/bundler/TROUBLESHOOTING.md).
+For help with common problems, see [TROUBLESHOOTING](../doc/TROUBLESHOOTING.md).
 
 Still stuck? Try [filing an issue](https://github.com/ruby/rubygems/issues/new?labels=Bundler&template=bundler-related-issue.md).
 
-## Other questions
-
-To see what has changed in recent versions of Bundler, see the [CHANGELOG](CHANGELOG.md).
-
-To get in touch with the Bundler core team and other Bundler users, please join [the Bundler slack](https://join.slack.com/t/bundler/shared_invite/zt-1rrsuuv3m-OmXKWQf8K6iSla4~F1DBjQ).
-
 ## Contributing
 
-If you'd like to contribute to Bundler, that's awesome, and we <3 you. We've put together [the Bundler contributor guide](https://github.com/ruby/rubygems/blob/master/doc/bundler/contributing/README.md) with all of the information you need to get started.
-
-If you'd like to request a substantial change to Bundler or its documentation, refer to the [Bundler RFC process](https://github.com/rubygems/rfcs) for more information.
+If you'd like to contribute to Bundler, that's awesome, and we <3 you. We've put together [contributor guide](https://github.com/ruby/rubygems/blob/master/CONTRIBUTING.md) with all of the information you need to get started.
 
 ## Supporting
 

doc/bundler/development/DEBUGGING.md → doc/DEBUGGING.md

@@ -2,7 +2,7 @@
 
 Debugging Bundler can be challenging, don't be discouraged 🤗.
 
-Make sure you've followed the [development setup](SETUP.md) docs before trying to debug.
+Make sure you've followed the [development setup](GETTING_STARTED.md) docs before trying to debug.
 
 ## Print debugging
 
@@ -50,7 +50,7 @@ RUBYOPT=-rpry-byebug dbundle # for pry-byebug
 
 ### Local setup
 
-The easiest way to test locally is to set up a directory with a Gemfile and run your Bundler shell alias (see the [development setup](SETUP.md) docs for instructions on setting up the alias).
+The easiest way to test locally is to set up a directory with a Gemfile and run your Bundler shell alias (see the [development setup](GETTING_STARTED.md) docs for instructions on setting up the alias).
 
 We recommend putting this directory inside of `tmp` so that your local tests don't accidentally get committed.
 

doc/DOCUMENTATION.md

@@ -0,0 +1,155 @@
+# Documentation
+
+Code needs explanation, and sometimes those who know the code well have trouble explaining it to someone just getting into it. We welcome documentation suggestions and patches from everyone, especially from those new to RubyGems or Bundler.
+
+This repository contains documentation for both RubyGems and Bundler. We have multiple documentation sources depending on what you're documenting:
+
+## RubyGems Documentation
+
+**RubyGems guides**: https://guides.rubygems.org/
+
+For RubyGems documentation contributions:
+- Submit issues or pull requests to the [RubyGems Guides repository](https://github.com/rubygems/guides)
+- This covers topics like gem creation, publishing, versioning, and best practices
+
+## Bundler Documentation
+
+**Bundler help & man pages**: Built into the `bundler/` directory
+
+**Bundler documentation site**: https://bundler.io
+
+For Bundler documentation contributions:
+- **Command documentation** (ex: `bundle clean`): Contribute to man pages in this repository (`bundler/lib/bundler/man/`)
+- **Guides and tutorials** (ex: "Using Bundler with Rails"): Open an issue or pull request in the [bundler-site](https://github.com/rubygems/bundler-site) repository
+- **Using Bundler with gems**: Additional documentation on [RubyGems guides](https://guides.rubygems.org/)
+
+## Documentation Vision and Goals
+
+### RubyGems
+
+RubyGems documentation focuses on:
+- Gem creation, packaging, and publishing
+- Dependency management best practices
+- Version constraints and semantic versioning
+- Security and trust topics
+
+Goals are to provide guides and tutorials at https://guides.rubygems.org/ that help users understand and effectively use RubyGems.
+
+### Bundler
+
+Bundler documentation is split across multiple places:
+
+1. Built-in `help` (including usage information and man pages)
+2. [Bundler documentation site](https://bundler.io)
+3. [RubyGems guides](https://guides.rubygems.org/) (for gem publishing topics)
+
+Bundler documentation should provide users with assistance:
+
+1. Installing Bundler
+2. Using Bundler to manage an application's dependencies
+3. Using Bundler to create, package, and publish gems
+
+Our goal is to provide three types of documentation:
+
+* High-level overviews that provide topical guidance
+* Step-by-step tutorials
+* Command-specific reference material for the CLI
+
+Additionally, this documentation should be readily available in a logical place and easy to follow.
+
+Someday, we'd like to create deep-dive reference material about the inner workings of Bundler. However, while this is part of our overall vision, it is not the focus of our current work.
+
+## Writing RubyGems Documentation
+
+### Contributing to RubyGems guides
+
+To contribute to RubyGems documentation:
+
+1. Fork and clone the [rubygems/guides](https://github.com/rubygems/guides) repository
+2. Add or edit Markdown files in the `_pages/` directory
+3. Follow the existing format and style guidelines
+4. Submit a pull request with your changes
+
+See the [RubyGems Guides repository](https://github.com/rubygems/guides) for detailed contribution instructions.
+
+## Writing Bundler Documentation
+
+### Writing docs for man pages
+
+*Any commands or file paths in this document assume that you are inside [the bundler/ directory of the ruby/rubygems repository](https://github.com/ruby/rubygems/tree/master/bundler).*
+
+A primary source of help for Bundler users are the man pages: the output printed when you run `bundle help` (or `bundler help`). These pages can be a little tricky to format and preview, but are pretty straightforward once you get the hang of it.
+
+_Note: `bundler` and `bundle` may be used interchangeably in the CLI. This guide uses `bundle` because it's cuter._
+
+### What goes in man pages?
+
+We use man pages for Bundler commands used in the CLI (command line interface). They can vary in length from large (see `bundle install`) to very short (see `bundle clean`).
+
+To see a list of commands available in the Bundler CLI, type:
+
+      $ bundle help
+
+Our goal is to have a man page for every command.
+
+Don't see a man page for a command? Make a new page and send us a PR! We also welcome edits to existing pages.
+
+### Creating a new man page
+
+To create a new man page, simply create a new `.ronn` file in the `lib/bundler/man/` directory.
+
+For example: to create a man page for the command `bundle cookies` (not a real command, sadly), I would create a file `lib/bundler/man/bundle-cookies.1.ronn` and add my documentation there.
+
+### Formatting
+
+Our man pages use ronn formatting, a combination of Markdown and standard man page conventions. It can be a little weird getting used to it at first, especially if you've used Markdown a lot.
+
+[The ronn guide formatting guide](https://rtomayko.github.io/ronn/ronn.7.html) provides a good overview of the common types of formatting.
+
+In general, make your page look like the other pages: utilize sections like `##OPTIONS` and formatting like code blocks and definition lists where appropriate.
+
+If you're not sure if the formatting looks right, that's ok! Make a pull request with what you've got and we'll take a peek.
+
+### Previewing
+
+To preview your changes as they will print out for Bundler users, you'll need to run a series of commands:
+
+```
+$ bin/rake dev:deps
+$ bin/rake man:build
+$ man ./lib/bundler/man/bundle-cookies.1
+```
+
+If you make more changes to `bundle-cookies.1.ronn`, you'll need to run the `bin/rake man:build` again before previewing.
+
+### Testing
+
+We have tests for our documentation! The most important test file to run before you make your pull request is the one for the `help` command and another for documentation quality.
+
+```
+$ bin/rspec ./spec/commands/help_spec.rb
+$ bin/rspec ./spec/quality_spec.rb
+```
+
+## Writing docs for [the Bundler documentation site](https://bundler.io)
+
+### Primary commands and utilities
+
+If you'd like to submit a pull request for any of the primary commands or utilities on [the Bundler documentation site](https://bundler.io), please follow the instructions above for writing documentation for man pages from the `ruby/rubygems` repository. They are the same in each case.
+
+**Note**: Editing `.ronn` files from the `ruby/rubygems` repository for the primary commands and utilities documentation is all you need 🎉. There is no need to manually change anything in the `rubygems/bundler-site` repository, because the man pages and the docs for primary commands and utilities on [the Bundler documentation site](https://bundler.io) are one in the same. They are generated automatically from the `ruby/rubygems` repository's `.ronn` files when you run `bin/rake man:build`.
+
+### Guides and tutorials
+
+To add a guide or tutorial to the [Bundler documentation site](https://bundler.io):
+
+1. Go to the [bundler-site](https://github.com/rubygems/bundler-site) repository
+2. Navigate to `/bundler-site/source/current_version_of_bundler/guides`
+3. Add a new [Markdown file](https://guides.github.com/features/mastering-markdown/) (ending in `.md`)
+4. Format the title correctly:
+   ```
+   ---
+   title: Your Guide Title Here
+   ---
+   ```
+5. Submit a pull request with your changes