|
| 1 | +# Segment Docs Contributors Guide |
| 2 | + |
| 3 | +Thanks for helpin' out! We really appreciate it. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | +There are three ways to contribute. |
| 9 | +- EASY: [Contribute from the Github web UI](#contribute-from-the-github-web-ui) - only use this when making small edits to existing text files |
| 10 | +- INTERMEDIATE: [Contribute using Git and Atom](#contribute-using-git-and-atom) - use this for everything else |
| 11 | +- ADVANCED: [Contribute using Git](#contribute-using-git-native-commands) - if you're a git nerd, you can use this method |
| 12 | + |
| 13 | +If you're changing how the docs render, adding files or changing images, you should use the intermediate or advanced options. |
| 14 | + |
| 15 | +This guide also contains a bunch of [useful formatting tips and tricks](#tips-and-tricks), plus instructions on how to [set up to run the docs locally](#set-up-on-mac-using-the-env-script), and how to [refresh the docs-catalog files](#refresh-the-segment-catalog). |
| 16 | + |
| 17 | + |
| 18 | +## Contribute from the Github web UI |
| 19 | + |
| 20 | +> **Use this method when making small edits to an existing file only.** |
| 21 | +> Don’t use this when: |
| 22 | +> - Editing more than one file at a time, |
| 23 | +> - Adding or removing image files |
| 24 | +> - Making edits that change how the docs or docs navigation works. |
| 25 | +> |
| 26 | +> In those cases, set up to [contribute using Atom], and run the docs locally to confirm that your changes work and render as expected. |
| 27 | +
|
| 28 | +1. Go to https://github.com/segmentio/segment-docs/tree/master/src, find the file you want to edit, and click the Pencil icon - “Edit this file” |
| 29 | +  |
| 30 | +2. Make your changes. |
| 31 | +3. Scroll all the way to the bottom and make a note about your change. |
| 32 | +  |
| 33 | +4. Click **Propose file change**. |
| 34 | +5. On the next screen, add a reviewer or two. |
| 35 | + These should be folks who know enough about the content change to give it a thumbs up. If you don't know who that is, you can also tag @sanscontext for a docs-team review. |
| 36 | +6. Once someone has reviewed and approved the change, merge the change. |
| 37 | +7. Delete the branch once the change has been merged! |
| 38 | + |
| 39 | +**If changes are needed on your Github PR**: You (or they) can add Github "suggestions", which you can merge into your PR one by one. If there are many updates, you might need to check out your branch using the Atom and Git process below to make the changes in a single commit. |
| 40 | + |
| 41 | +## Contribute using Git and Atom |
| 42 | + |
| 43 | +If you are adding files, changing images, making large or long-running changes to some docs, or changing how the docs are ordered or rendered, you should use Git. If you're not a git-native, your best bet is to use Atom, the Github-created open-source editor. This requires a bit of setup the first time, but we'll put that in a separate section! |
| 44 | + |
| 45 | +> ℹ️ **Before you begin**: Make sure you've installed Atom. You can either install as part of running the `make env` command [described below](), or by > following the [Atom installation instructions](https://flight-manual.atom.io/getting-started/sections/installing-atom/). |
| 46 | +
|
| 47 | +1. Open Atom, and make sure the Git tool panel is open. |
| 48 | + (Press `Ctrl + Shift + 9` to open or close it, or find it in the **Packages** menu in Atom.) |
| 49 | +2. Switch to the `master` branch, and update/fetch master from within Atom, using the 🔄 Fetch button |
| 50 | +  |
| 51 | +3. Create a new branch from `master`. This is where you’ll commit your changes. |
| 52 | +  |
| 53 | +4. Make your changes, and save the files you’ve changed. |
| 54 | +5. Stage changes. This means you mark them as specific files that you want to save and check in. |
| 55 | +6. Add a short commit message, and click **Commit to (branchname)**. This adds a save point to your branch. |
| 56 | +  |
| 57 | + |
| 58 | +7. Click **Publish** (or **Push**). |
| 59 | + |
| 60 | +8. Go to the [Segment-docs repo in Github](https://github.com/segmentio/segment-docs), and create new Pull Request (PR). |
| 61 | + A pull request is how you ask to add your changes to the public version of the documentation. |
| 62 | + If you recently pushed a new branch, Github will prompt you to open a PR by clicking the Compare & pull request button. |
| 63 | +  |
| 64 | + (If you don’t see this, you can go to **Pull requests** tab, and click **New pull request**, then in the second drop down, find your branch name.) |
| 65 | +9. Open your Pull request. |
| 66 | + 1. Add a good title that explains what your change does. |
| 67 | + 2. Fill out the template sections. At minimum you should explain what this change does, but you can also link to Github issues or Jiras, or other conversations about the issue you’re fixing. |
| 68 | +  |
| 69 | +10. Next, request a review or two. One person should be able to check for typos, the other for technical inaccuracies. |
| 70 | + |
| 71 | + If you’re making a large change, you should include someone from the Engineering or Product teams. |
| 72 | + Github will suggest the last few people who edited that file. That’s often a good way to go! If not, you can requesting a review from sanscontext. |
| 73 | +  |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +### Making review edits in a PR |
| 78 | + |
| 79 | +Your reviewers might ask you to make changes to your PR before merging it. You can do this easily in Atom: Just follow steps 4-7 above as needed. (Make the change(s), save the file(s), stage them, write a commit message, and push.) They’ll get added to the changes already in the branch in your Pull Request! |
| 80 | + |
| 81 | +Once your PR has been reviewed, approved, and all the automated tests completed, click **Squash and Merge**, and then **Delete branch** to clean up after yourself! |
| 82 | + |
| 83 | +Back in Atom, you can do a bit of pre-work by selecting the `master` branch and clicking and **Pull**. Now you're ready for the next edits! |
| 84 | + |
| 85 | + |
| 86 | +## Contribute using git native commands |
| 87 | + |
| 88 | +This section is a very sparse outline of a git flow for git-experts and other folks with strong opinions about Atom. ;) It assumes that you have a favorite text editor, git installed, and that you've already set done a `git clone` to create the local segment-docs repo. |
| 89 | + |
| 90 | +1. Change to and update master (`git checkout master && git pull`) |
| 91 | +2. Create a new branch from master (`git checkout -b my_new_branch`) |
| 92 | +3. Make changes, save them. |
| 93 | +4. Stage your changes (`git status` and `git add` the appropriate files) |
| 94 | +5. Commit staged changes to your branch (`git commit`) |
| 95 | +6. Push your branch and changes to the `segment-docs` repo (`git push`, `git push --set-upstream origin`) |
| 96 | +7. Repeat steps 3-6 as needed. |
| 97 | +8. Open a PR by [going to the PRs page](https://github.com/segmentio/segment-docs/pulls), if not prompted, create new by selecting `master` as base, `(your branch name)` as other. |
| 98 | +9. Request a review. The Codeowners should populate this, and if not you can tag @sanscontext. |
| 99 | +10. If changes are requested, repeat steps 3-6 as needed. |
| 100 | +11. Once approved, merge and delete branch, delete branch locally. |
| 101 | + |
| 102 | + |
| 103 | +## Tips and tricks |
| 104 | + |
| 105 | + |
| 106 | +### Adding links that open in a new window |
| 107 | + |
| 108 | +Use the standard markdown format for links (ex: `[text](https://example.com)`). |
| 109 | +To make a link open in a new tab append `[text](https://example.com){:target="_blank"}` to the end. |
| 110 | + |
| 111 | +### Escaping code snippets |
| 112 | + |
| 113 | +Certain code syntax will be interpreted by Jekyll/Liquid as site code. If you're having trouble showing code snippets in the docs, you can wrap the snippet in a `{% raw %}` tag. In the example below, the curly brackets would not render in the docs. The raw tags ensure the code renders properly. |
| 114 | + |
| 115 | +``` |
| 116 | +{% raw %} |
| 117 | +To pass source name in the slack message, format it like so: `{{properties.sourceName}}` |
| 118 | +{% endraw %} |
| 119 | +``` |
| 120 | + |
| 121 | + |
| 122 | +### Syntax highlighting |
| 123 | + |
| 124 | +We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉. |
| 125 | +A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers). |
| 126 | + |
| 127 | +### Note Blocks |
| 128 | +We're using [Premonition](https://github.com/lazee/premonition) for our Note blocks. This is stock right now, with four styles: `note`, `info`, `success`, `warning`, and `error`. |
| 129 | + |
| 130 | +You'd write a block like this: |
| 131 | +```md |
| 132 | +> warning "I am a warning" |
| 133 | +> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block. |
| 134 | +``` |
| 135 | + |
| 136 | +Notes *must* include a `[]` in the heading/title, even if it's empty. |
| 137 | +You can see how to write them in the `styleguide.md`, and see how they render at [https://segment.build/docs/styleguide](https://segment.build/docs/styleguide) |
| 138 | + |
| 139 | +### Redirect to a workspace |
| 140 | +Occasionally, you'll want to deep-link into the Segment app to link a reader to a specific page or screen. Previously we'd throw them an URL and say "replace {MY SLUG} with your actual workspace slug", but now you can use the slug of `goto-my-workspace` and the Segment app will redirect them. |
| 141 | +https://app.segment.com/goto-my-workspace/destinations/catalog |
| 142 | + |
| 143 | + |
| 144 | + |
| 145 | +## Set up on Mac using the Env script |
| 146 | + |
| 147 | +We've written a bash script to set up the environment for you on a Mac computer. If you're on another platform, please [email us ](mailto:[email protected]) or [file a Github Issue ](https://github.com/segmentio/segment-docs/issues/new) to request other instructions, and we'll see what we can do. |
| 148 | + |
| 149 | +> info "" |
| 150 | +> You only need to run `make env` once! |
| 151 | +
|
| 152 | +1. Set up your Github config so you have an SSH key on your laptop. |
| 153 | +2. Clone this repo locally. |
| 154 | +3. Open your Terminal app and navigate to where you cloned the docs repo. |
| 155 | +4. Start by checking what directory you’re in, to make sure you’re in the `segment-docs` repo. |
| 156 | + Type `pwd` (which means “print working directory”) to check. You should see something like `~/repos/segment-docs`. |
| 157 | +5. Type `make env`. |
| 158 | + The script first checks to see if you have Brew installed, and if you don’t, it installs it. It then runs more brew commands to download and install the software you need. |
| 159 | + |
| 160 | + > **Heads up**! You’re going to need to enter your laptop password as part of this installation, but only once! |
| 161 | +
|
| 162 | + Once the installer completes, you still need to do a few small configuration tasks. |
| 163 | + |
| 164 | +6. Open the Atom app, then click the **Atom** menu in the top left, and click **Install Shell Commands**. |
| 165 | +7. Next, make sure you’re showing invisible characters. These are important for seeing weird formatting in the docs, and for troubleshooting markdown. |
| 166 | + Go to **Preferences > Editor**, and scroll down to **Show Invisibles**. Make sure that’s checked! |
| 167 | +  |
| 168 | + |
| 169 | +8. Finally, configure bash completion by adding tab-completion to your `.bash` profile: |
| 170 | + |
| 171 | + 1. Open Terminal and type `atom ~/.bash_profile` to open the file in Atom. |
| 172 | + 2. Paste the following anywhere in the file: |
| 173 | + `[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"` |
| 174 | + 3. Save and close the file in Atom. |
| 175 | + 4. Quit and relaunch both Terminal and Atom. |
| 176 | + |
| 177 | +## Refresh the Segment catalog |
| 178 | + |
| 179 | +The Segment Docs pull a list of sources and destinations from the public ConfigAPI's Catalog API endpoint. We save these files locally (in YML files in `src/_data/catalog/`) so that you can run the docs locally without needing to touch the ConfigAPI, but these files can fall out of date. |
| 180 | + |
| 181 | +To update the files, you run `make catalog` from your Terminal. Before you can do that, follow the instructions below: |
| 182 | + |
| 183 | +### Set up to refresh the Segment catalog |
| 184 | + |
| 185 | +To use the `make catalog` command to update the list of sources and destinations that Segment supports, you'll need [a basic token for the Segment ConfigAPI](https://segment.com/docs/config-api/authentication/). You'll save this in a `.env` file on your computer, which will allow the script to talk to the Segment APIs. |
| 186 | + |
| 187 | +1. If you don't already have one, sign up for a free Segment workspace. |
| 188 | +2. Copy the `.env.example` file at the root of this directory, and rename it to remove the word "example". It should *just* be called `.env` when you're done. **Do NOT check in your .env file.** |
| 189 | +2. Go to the workspace's **Settings > Access Management > Tokens** tab (or click [here](https://app.segment.com/goto-my-workspace/settings/access-management)). |
| 190 | +3. Click **Create Token**. |
| 191 | +4. Add a description (you and specify that you're using it for docs purposes). |
| 192 | +5. Select **Workspace Member**, check **Source Admin**, and select one or all sources. You can grant this token more privileges, but that is unnecessary for this use. |
| 193 | +5. Click **Create**. |
| 194 | +6. Copy the token payload, and paste it after the equals sign (`=`) after "PLATFORM_API_TOKEN". |
| 195 | +7. Save and close the file. Before running the make command you may need to type `env` and enter into Terminal, or otherwise restart your Terminal session. |
0 commit comments