Skip to content

Commit c018297

Browse files
devalogdevalog
committed
add draft of rubygems publishing guide
1 parent e6dbeea commit c018297

File tree

2 files changed

+211
-2
lines changed

2 files changed

+211
-2
lines changed

‎fern/products/sdks/overview/ruby/assets/new-api-key.png‎

226 KB
Loading

‎fern/products/sdks/overview/ruby/publishing-to-rubygems.mdx‎

Lines changed: 211 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,215 @@ title: Publishing to RubyGems
33
description: How to publish the Fern Ruby SDK to RubyGems.
44
---
55

6-
Learn how to publish your Fern Ruby SDK to the RubyGems registry.
6+
Publish your public-facing Fern Ruby SDK to the [RubyGems
7+
registry](https://rubygems.org/). After following the steps on this page,
8+
you'll have a versioned package published on RubyGems.
79

8-
<Warning>This page is a WIP, please refer to our previous [documentation](https://buildwithfern.com/learn/sdks/guides/publish-a-public-facing-sdk).</Warning>
10+
<Frame>
11+
<img src="assets/pypi-package.png" alt="Versioned package published on RubyGems" />
12+
</Frame>
13+
14+
<Info>This guide assumes that you already have an initialized `fern` folder on your local machine. If you don’t, run `fern init`. See [ruby Quickstart](quickstart.mdx) for more details.</Info>
15+
16+
## Set up your GitHub integration
17+
18+
1. Create a new GitHub repository called `company-ruby` (or something similar) for your SDK, if you haven't done so already.
19+
1. Install the [Fern GitHub App](https://github.com/apps/fern-api): Select **Configure**, then scroll down to **Repository Access**. Select **Only select repositories** and in the dropdown select the repository for your SDK. Click **Save**.
20+
21+
22+
## Configure `generators.yml`
23+
24+
<Steps>
25+
26+
<Step title="Run `fern add <generator>`">
27+
28+
Navigate to your `generators.yml` on your local machine. Your `generators.yml` lives inside of your `fern` folder and contains all the configuration for your Fern generators.
29+
30+
Add a new generator to `generators.yml`:
31+
32+
33+
```bash
34+
fern add fern-ruby-sdk --group ruby-sdk
35+
```
36+
37+
Once the command completes, you'll see a new group created in your `generators.yml`:
38+
39+
```yaml {3-9}
40+
groups:
41+
...
42+
ruby-sdk:
43+
generators:
44+
- name: fernapi/fern-ruby-sdk
45+
version: <Markdown src="/snippets/version-number.mdx"/>
46+
output:
47+
location: local-file-system
48+
path: ../sdks/ruby
49+
```
50+
51+
</Step>
52+
53+
<Step title="Configure `output` location">
54+
55+
Next, change the output location in `generators.yml` from `local-file-system` (the default) to `pypi` to indicate that Fern should publish your package directly to the PyPI registry:
56+
57+
```yaml {6-7}
58+
groups:
59+
ruby-sdk:
60+
generators:
61+
- name: fernapi/fern-ruby-sdk
62+
version: <Markdown src="/snippets/version-number.mdx"/>
63+
output:
64+
location: rubygems
65+
66+
```
67+
</Step>
68+
69+
<Step title="Add a unique package name">
70+
71+
Your package name must be unique in the RubyGems repository, otherwise publishing your SDK to RubyGems will fail. Update your package name if you haven't done so already:
72+
73+
74+
```yaml {8}
75+
groups:
76+
ruby-sdk:
77+
generators:
78+
- name: fernapi/fern-ruby-sdk
79+
version: <Markdown src="/snippets/version-number.mdx"/>
80+
output:
81+
location: rubygems
82+
package-name: your-package-name
83+
```
84+
85+
</Step>
86+
<Step title="Configure `clientClassName`">
87+
88+
The `clientClassName` option controls the name of the generated client. This is the name customers use to import your SDK (`import { your-client-name } from 'your-package-name';`).
89+
90+
91+
```yaml {9-10}
92+
groups:
93+
ruby-sdk:
94+
generators:
95+
- name: fernapi/fern-ruby-sdk
96+
version: <Markdown src="/snippets/version-number.mdx"/>
97+
output:
98+
location: rubygems
99+
package-name: your-package-name
100+
config:
101+
clientClassName: YourClientName # must be PascalCase
102+
```
103+
104+
</Step>
105+
106+
<Step title="Add repository location">
107+
108+
Add the path to your GitHub repository to `generators.yml`:
109+
110+
```yaml {11-12}
111+
groups:
112+
ruby-sdk:
113+
generators:
114+
- name: fernapi/fern-ruby-sdk
115+
version: <Markdown src="/snippets/version-number.mdx"/>
116+
output:
117+
location: rubygems
118+
package-name: your-package-name
119+
config:
120+
clientClassName: YourClientName
121+
github:
122+
repository: your-org/company-ruby
123+
```
124+
125+
</Step>
126+
</Steps>
127+
128+
## Set up RubyGems publishing authentication
129+
130+
<Steps>
131+
132+
<Step title="Log into RubyGems">
133+
134+
Log into [RubyGems](https://pypi.org/) or create a new account.
135+
136+
</Step>
137+
138+
<Step title="Navigate to Account settings">
139+
140+
1. Click on your profile picture
141+
1. Select **Settings**.
142+
1. Scroll down and click on **API Keys**.
143+
144+
</Step>
145+
146+
<Step title="Add New Key">
147+
148+
When prompted to [create a new API key](https://rubygems.org/profile/api_keys/new):
149+
1. Name your key.
150+
1. Under **Scopes**, select **Push rubygem**
151+
1. Select `All Gems` under **Gem Scope**.
152+
<Tip title="Replacing an existing gem">
153+
If you are overriding an existing gem, you can select the relevant package instead of entering `All Gems`.
154+
</Tip>
155+
1. Set an expiration date.
156+
1. Click **Create API Key**.
157+
158+
<Frame>
159+
<img src="assets/new-api-key.png" alt="Creating a New API Key" />
160+
</Frame>
161+
162+
<Warning>Save your new key – it won’t be displayed after you leave the page.</Warning>
163+
164+
</Step>
165+
166+
<Step title="Configure RubyGems authentication token">
167+
168+
Add `api-key: ${RUBYGEMS_API_KEY}` to `generators.yml` to tell Fern to use the `RUBYGEMS_API_KEY` environment variable for authentication when publishing to the PyPI registry.
169+
170+
```yaml title="ruby" {9}
171+
groups:
172+
ruby-sdk:
173+
generators:
174+
- name: fernapi/fern-ruby-sdk
175+
version: <Markdown src="/snippets/version-number.mdx"/>
176+
output:
177+
location: rubygems
178+
package-name: your-package-name
179+
api-key: ${RUBYGEMS_API_KEY}
180+
config:
181+
clientClassName: YourClientName
182+
github:
183+
repository: your-org/company-ruby
184+
```
185+
</Step>
186+
187+
</Steps>
188+
189+
## Release your SDK to RubyGems
190+
191+
At this point, you're ready to generate a release for your SDK.
192+
193+
<Steps>
194+
195+
<Step title="Set RubyGems environment variable">
196+
197+
On your local machine, set the `RUBYGEMS_API_KEY` environment variable to the new API key you generated earlier:
198+
199+
```bash
200+
export RUBYGEMS_API_KEY=your-actual-rubygems-token
201+
```
202+
203+
</Step>
204+
205+
<Step title="Generate your release">
206+
207+
Regenerate your SDK and publish it on RubyGems:
208+
209+
```bash
210+
fern generate --group ruby-sdk --version <version>
211+
```
212+
Local machine output will verify that the release is pushed to your
213+
repository and tagged with the version you specified. Log back into RubyGems and
214+
navigate to **Your projects** to see your new release.
215+
</Step>
216+
217+
</Steps>

0 commit comments

Comments
 (0)