You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: doc/DOCUMENTATION.md
+37-82Lines changed: 37 additions & 82 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,83 +2,59 @@
2
2
3
3
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.
4
4
5
-
This repository contains documentation for both RubyGems and Bundler. We have multiple documentation sources depending on what you're documenting:
5
+
## Where to contribute
6
6
7
-
## RubyGems Documentation
7
+
Documentation for RubyGems and Bundler is managed in two places:
8
8
9
-
**RubyGems guides**: https://guides.rubygems.org/
9
+
-**Guides and tutorials**: [RubyGems Guides](https://guides.rubygems.org/) — hosted in the [rubygems/guides](https://github.com/rubygems/guides) repository
10
+
-**Bundler CLI man pages**: Built from `.ronn` files in `bundler/lib/bundler/man/` in this repository and published to [bundler.io](https://bundler.io)
10
11
11
-
For RubyGems documentation contributions:
12
-
- Submit issues or pull requests to the [RubyGems Guides repository](https://github.com/rubygems/guides)
13
-
- This covers topics like gem creation, publishing, versioning, and best practices
14
-
15
-
## Bundler Documentation
16
-
17
-
**Bundler help & man pages**: Built into the `bundler/` directory
-**Command documentation** (ex: `bundle clean`): Contribute to man pages in this repository (`bundler/lib/bundler/man/`)
23
-
-**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
24
-
-**Using Bundler with gems**: Additional documentation on [RubyGems guides](https://guides.rubygems.org/)
12
+
All documentation other than Bundler command man pages — including guides, tutorials, and reference material for both RubyGems and Bundler — should be contributed to the [rubygems/guides](https://github.com/rubygems/guides) repository.
25
13
26
14
## Documentation Vision and Goals
27
15
28
-
### RubyGems
29
-
30
-
RubyGems documentation focuses on:
31
-
- Gem creation, packaging, and publishing
32
-
- Dependency management best practices
33
-
- Version constraints and semantic versioning
34
-
- Security and trust topics
35
-
36
-
Goals are to provide guides and tutorials at https://guides.rubygems.org/ that help users understand and effectively use RubyGems.
37
-
38
-
### Bundler
39
-
40
-
Bundler documentation is split across multiple places:
41
-
42
-
1. Built-in `help` (including usage information and man pages)
Bundler documentation should provide users with assistance:
47
-
48
-
1. Installing Bundler
49
-
2. Using Bundler to manage an application's dependencies
50
-
3. Using Bundler to create, package, and publish gems
51
-
52
16
Our goal is to provide three types of documentation:
53
17
54
18
* High-level overviews that provide topical guidance
55
19
* Step-by-step tutorials
56
20
* Command-specific reference material for the CLI
57
21
22
+
Topics include:
23
+
24
+
- Gem creation, packaging, and publishing
25
+
- Dependency management best practices
26
+
- Version constraints and semantic versioning
27
+
- Security and trust
28
+
- Installing and using Bundler
29
+
- Managing application dependencies with Bundler
30
+
58
31
Additionally, this documentation should be readily available in a logical place and easy to follow.
59
32
60
33
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.
61
34
62
-
## Writing RubyGems Documentation
63
-
64
-
### Contributing to RubyGems guides
35
+
## Writing guides and tutorials
65
36
66
-
To contribute to RubyGems documentation:
37
+
To contribute to [RubyGems Guides](https://guides.rubygems.org/):
67
38
68
39
1. Fork and clone the [rubygems/guides](https://github.com/rubygems/guides) repository
69
-
2. Add or edit Markdown files in the `_pages/` directory
70
-
3. Follow the existing format and style guidelines
40
+
2. Add or edit a Markdown file in the root directory
41
+
3. Include the required frontmatter:
42
+
```
43
+
---
44
+
layout: default
45
+
title: Your Guide Title Here
46
+
url: /your_guide_url
47
+
previous: /previous_guide
48
+
next: /next_guide
49
+
---
50
+
```
71
51
4. Submit a pull request with your changes
72
52
73
-
See the [RubyGems Guides repository](https://github.com/rubygems/guides) for detailed contribution instructions.
53
+
See the [rubygems/guides README](https://github.com/rubygems/guides#readme) for setup and preview instructions.
74
54
75
-
## Writing Bundler Documentation
55
+
## Writing Bundler man pages
76
56
77
-
### Writing docs for man pages
78
-
79
-
*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).*
80
-
81
-
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.
57
+
Man pages are 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.
82
58
83
59
_Note: `bundler` and `bundle` may be used interchangeably in the CLI. This guide uses `bundle` because it's cuter._
84
60
@@ -96,9 +72,9 @@ Don't see a man page for a command? Make a new page and send us a PR! We also we
96
72
97
73
### Creating a new man page
98
74
99
-
To create a new man page, simply create a new `.ronn` file in the `lib/bundler/man/` directory.
75
+
To create a new man page, simply create a new `.ronn` file in the `bundler/lib/bundler/man/` directory.
100
76
101
-
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.
77
+
For example: to create a man page for the command `bundle cookies` (not a real command, sadly), I would create a file `bundler/lib/bundler/man/bundle-cookies.1.ronn` and add my documentation there.
102
78
103
79
### Formatting
104
80
@@ -117,39 +93,18 @@ To preview your changes as they will print out for Bundler users, you'll need to
117
93
```
118
94
$ bin/rake dev:deps
119
95
$ bin/rake man:build
120
-
$ man ./lib/bundler/man/bundle-cookies.1
96
+
$ man ./bundler/lib/bundler/man/bundle-cookies.1
121
97
```
122
98
123
99
If you make more changes to `bundle-cookies.1.ronn`, you'll need to run the `bin/rake man:build` again before previewing.
124
100
101
+
The [Bundler documentation site](https://bundler.io) is automatically generated from these `.ronn` files.
102
+
125
103
### Testing
126
104
127
105
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.
128
106
129
107
```
130
-
$ bin/rspec ./spec/commands/help_spec.rb
131
-
$ bin/rspec ./spec/quality_spec.rb
108
+
$ bin/rspec spec/commands/help_spec.rb
109
+
$ bin/rspec spec/quality_spec.rb
132
110
```
133
-
134
-
## Writing docs for [the Bundler documentation site](https://bundler.io)
135
-
136
-
### Primary commands and utilities
137
-
138
-
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.
139
-
140
-
**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`.
141
-
142
-
### Guides and tutorials
143
-
144
-
To add a guide or tutorial to the [Bundler documentation site](https://bundler.io):
145
-
146
-
1. Go to the [bundler-site](https://github.com/rubygems/bundler-site) repository
147
-
2. Navigate to `/bundler-site/source/current_version_of_bundler/guides`
148
-
3. Add a new [Markdown file](https://guides.github.com/features/mastering-markdown/) (ending in `.md`)
Copy file name to clipboardExpand all lines: doc/GETTING_STARTED.md
+17-9Lines changed: 17 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
[Fork the ruby/rubygems repo](https://github.com/ruby/rubygems) and clone the fork onto your machine. ([Follow this tutorial](https://help.github.com/articles/fork-a-repo/) for instructions on forking a repo.)
6
6
7
-
Install development dependencies from the repository root directory:
7
+
This repository does not have a root `Gemfile`. Development dependencies are managed through purpose-specific gem files in `tool/bundler/` (e.g., `test_gems.rb`, `rubocop_gems.rb`). Use the following rake task instead of `bundle install`:
8
8
9
9
bin/rake setup
10
10
@@ -35,7 +35,9 @@ To run Bundler commands like `bundle install` from your local copy:
35
35
36
36
## Running Tests
37
37
38
-
### RubyGems Tests
38
+
RubyGems uses [test-unit](https://github.com/test-unit/test-unit) and Bundler uses [RSpec](https://rspec.info/). Each has its own test commands.
39
+
40
+
### RubyGems Tests (test-unit)
39
41
40
42
To run the entire RubyGems test suite:
41
43
@@ -49,20 +51,26 @@ To run a specific test method named `test_default`:
To run the entire Bundler test suite in parallel from the `bundler/` directory:
56
+
To run all Bundler specs (both regular and realworld):
55
57
56
-
bin/parallel_rspec
58
+
bin/rake spec:all
57
59
58
-
For realworld higher level specs (also run in CI):
60
+
This runs `spec:regular` and `spec:realworld`. The full suite takes 20-30 minutes.
59
61
60
-
bin/rake spec:realworld
61
-
62
-
To run an individual Bundler test file, for example `spec/install/gems/standalone_spec.rb`, from the `bundler/` directory:
62
+
To run an individual spec file:
63
63
64
64
bin/rspec spec/install/gems/standalone_spec.rb
65
65
66
+
To run multiple spec files or long-running specs in parallel:
67
+
68
+
bin/parallel_rspec spec/install
69
+
70
+
For realworld higher level specs (also run in CI):
71
+
72
+
bin/rake spec:realworld
73
+
66
74
## Developing Bundler and RubyGems Together
67
75
68
76
When developing Bundler features or bug fixes that require changes in RubyGems, you can set the `RGV` environment variable to point to the repository root so Bundler's test suite picks up those changes:
0 commit comments