diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..0d645f01c4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[docs-alerts@segment.com](mailto:docs-alerts@segment.com). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/README-old.md b/README-old.md deleted file mode 100644 index 662702bef4..0000000000 --- a/README-old.md +++ /dev/null @@ -1,227 +0,0 @@ -# segment-docs Readme! - -Hello, yes, this is docs. - - - -Here's what's here! - -We are now splitting out the Readme into three parts: -- [Contributor Guide](contributors.md) -- [Style Guide](styleguide.md) -- [Technical Details](devguide.md) - ---- -Here's what's on this main page: - - - -- [Contributing to the Segment Docs](#contributing-to-the-segment-docs) -- [Quickstart](#quickstart) -- [Most frequently asked question: Do I need a review?](#most-frequently-asked-question-do-i-need-a-review) -- [How to docs (The Docs Process)](#how-to-docs-the-docs-process) -- [How the docs build works](#how-the-docs-build-works) -- [Formatting and Prettifying](#formatting-and-prettifying) -- [Repo structure](#repo-structure) -- [Frontmatter](#frontmatter) -- [Navigation](#navigation) -- [Makefile commands](#makefile-commands) - - - - - - - - -## Contributing to the Segment Docs - -## Quickstart - -Git clone this repo, navigate to it in Terminal, run `make env`. -This installs everything you need to edit the docs **and** run the docs build locally. That done: Edit the content files locally, check them in on a new branch, go to Github and open a PR to the segment-docs repo, and when your PR is merged to `master`, the public docs site automatically rebuilds. - -If these instructions didn't make any sense to you, or for more details, see the [Contributor Guide](contributors.md)! - -### JUST Editing content? - -You can make a limited range of edits [from the Github site](contributors.md/#contribute-from-the-github-web-ui)! Hooray! But the Github UI [has some limitations](contributors.md#contribute-from-the-github-web-ui), and this system works best if you clone it locally so you can run test builds. - -See the [Contributor Guide](contributors.md) for more info. - -## Most frequently asked question: Do I need a review? - -**At minimum you must open a PR so the docs team gets a notification. Do not merge directly to master.** - -- **Just fixing a typo**? -> No review needed, but please label it FIX in the PR subject so we know not to worry. You can then admin-merge your PR with our blessings. - -- **Delta of <20 words or ~150 characters**? -> Yes, but a minor review. Open a PR and tag @sanscontext, who'll review mostly for formatting and copy issues. - -- **Adding new feature docs**? -> Yes. Get _two_ reviewers, one for technical accuracy, and one for copy. - - -## How to docs (The Docs Process) - -If you're planning substantial changes to the docs, follow this process for great success! 🏆 - -1. 📞 Contact the docs team ( @segmentio/segment-doc-team ) during the planning phase. This way, we can help with logistics and information architecture, and alert you to any gotchas in your content area. -2. 📝 Unless previously booked, we don't need to be involved in the writing - go for it! (We're happy to consult if you get stuck or need someone to bounce ideas off.) -3. 👀 When you've got a draft at least 70% ready for review, tag a member of the docs team, who'll do an initial review. (This can be either in Paper/Gdocs, or in a Github [Draft PR](#draft-prs) with markdown changes if you're comfortable with that.) They'll do a copy edit pass, and ask clarifying questions. -4. ❓The doc author/owner should answer the questions asked in the review phase. Either the doc author, or the docs team member can resolve comments as they are clarified in the doc text.👍 -5. ✅ The docs team member does a final review and approves. -6. 🚢 Once it's signed off, you publish! This can mean: - - The author opens a PR to publish their changes - - The author consults with a docs-team person to publish changes (esp good when making nav changes, moving or deleting pages) - - The docs person opens a PR to push the changes - -Once the PR is merged, the docs site rebuilds and the changes are live! - - -### The Docs Process for direct contributors - -1. Check out the repo and get set up. -2. Create a new branch and make your changes. - - Change the content in the files. - - If needed, update the appropriate file in the `src/_data/sidenav/` to reflect your changes. -3. Commit your changes. -3. Push the branch to `segment-docs` and make a PR to master. - - Include any context you can in the PR: links to ZD tickets, Jira tickets, Paper docs or wiki pages about the project. (If you include a Jira ticket number, Jira can often link directly to the PR.) -3. [Check if you need a review](#most-frequently-asked-question-do-i-need-a-review) and tag a member of the docs team. (Github also tags the CODEOWNERS for the path you're editing.) -5. If the reviewers ask for clarifications or edits: - - make the changes - - push the new commits to the branch -5. Once you get an approving review and the checks pass, merge your PR. -7. Once merged, Netlify builds the changes to `master` and redeploys the docs site. - -### Draft PRs - -If you're doing a substantial change and you're going to want to spend a few weeks on it, use [Github's Draft PRs feature](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests), or add `DRAFT` or `WIP` to the title of your PR. This lets us know to ignore the PR until you're ready (otherwise we might ping you weekly about it!). - - -## How the docs build works - -The actual content that you see on segment.com/docs lives in this repository in the `/src/` folder and its subdirectories. Everything outside of that folder is related to the build, styling, tracking, and process for this repo. - -These files are built by Jekyll, a Ruby static-site builder, into a full site of static HTML pages. We do not have any interactive or adaptive content on the site at this time. - -When you run `make dev` (or `make docs`) on your laptop, Jekyll runs the same program that it uses to create the public site html pages. It builds the page templates, then builds an HTML page for each markdown file (or html file) in the `src` path[**](#underscore-files). - -Some of these files include Liquid script, which allows them to load reusable content ("includes"), render fancy HTML styling, and run simple code processes to build programmatic content. As long as the Jekyll process is running on your laptop, you can edit the content of a page in markdown and save it, and Jekyll will detect the change and rebuild that page so you can view it locally. However, this doesn't work if you're editing the page layouts or stylesheets, which are assumed to be static at build time. - -When you merge a PR to master, the Netlify build system runs the Jekyll program, and automatically publishes the rebuilt HTML files. - -## Formatting and Prettifying -Some important tips are in the [styleguide](styleguide.md). We also have a (rendering) [Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered. - -## Repo structure - -All of the content files live in the `/src/` directory. Everything outside of this is related to the build. - -Within the `/src/` path, anything that starts with an underscore (like `_data` or `_includes`) is a utility directory, and Jekyll won't render it as a webpage path at build time. (In fact, any files where the name starts with an underscore are dropped from the build.) - -### Underscore files - -Anything that starts with an `_` is a utility directory of some sort (and Jekyll will skip/not render any file that starts with a `_`). - -The most interesting ones are: -- `/src/_includes/content/` This is where all the includes or "partials" - the reusable content - are stored. -- `/src/_data/catalog/` This is where we keep the data we've pulled from the ConfigAPI in structured `yml` files that are used by the build. -- `/src/_data/sidenav/` This is where the navigation structures are. (Several sections in the doc have their own left-nav, making them "microsites".) They're just YML files that we manually update so we have maximum control over what's shown and what's not. - - -### Images - -**Save all images locally! No linking to 3rd party-hosted images!** Images are published to our CDN from the build step, and this means they won't go missing if the hosting service dujour goes out of business. - -There are no _enforced_ naming conventions at this time. Files that start with an underscore are ignored by Jekyll. Anything you see with `asset` was dowloaded by a script to migrate it out of Contents.io. - -In general, it's a good practice to name images with a description that helps you (& other docs maintainers) figure out where they should go within a page, or within a larger folder of images. - -A few possibilities/suggestions: - -- **Add a prefix of what file the image appears in**. This is helpful if you have images for multiple pages in the same `images` directory, but breaks down a bit if you reuse images across multiple pages. -- **Give a prefix of the application the screenshot shows**. For example `atom-new-file.png`, `atom-commit-changes.png` etc), -- **Name images to describe a process flow**. For example `checkout-1-add-to-cart.png`, `checkout-2-est-shipping.png` and so on. - - -### Content structure - -There are folders for each of the top level products, and those folders might also contain topics that are related to that product area (for example the Privacy Portal section also contains GDPR/CCPA docs). - -For the Connections product, the section is divided into the Spec, then Sources, Destinations, and Storage Destinations (formerly called "Warehouses"), with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.) - -Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this `catalog` folder (the `index.md`) is a pretty "catalog" page which gives a tile-like view by category, suitable for browsing. It pulls the logo for these tiles from the path for the integration in the metadata, either in `destinations.yml`, `sources.yml`, or `warehouses.yml`. - - -### Programmatic content - -Programmatic content is sections of documentation that are built conditionally, or using public information from our Config API. This is *awesome* and like the holy grail of docs systems. - -Programmatic content is built using information in the files in `/src/_data/catalog/`. These files (with the exception of `warehouses.yml`) are built by the `make catalog` command, which contacts our public ConfigAPI, gets a list of all the available integrations using the Catalog API, and then parses them into static `.yml` files. - -Most of the programmatic content is built into the `_layouts` templates that each page uses. Sources, Destinations, and Warehouses use the `integration.html` template, which uses some Liquid logic, and calls an `include` depending on the integration type. Most of logic for the actual content must live in the include file itself, however logic controlling *if* the include is built can live in the `layout`. - -Destination pages include the `destination-dossier.html` and `destination_footer.md` content, which use Liquid scripting and pulls from the catalog metadata. - -Sources pages check if the source is a cloud-app, then include information about if the source is an object or event source, based on the `type` data from the ConfigAPI. - - -## Frontmatter - -Each Markdown file in the docs can have "frontmatter" associated with it at the top of the file. These are considered by Jekyll to be "properties" of a page, generally control how the HTML page is built or rendered. - -Frontmatter in a file will look something like this: - -```md ---- -title: Analytics.js Library -hide-feedback: false ---- -``` - -Each piece of frontmatter does something special! - -#### Content-related frontmatter -- `beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta-note.md`) -- `rewrite`: defaults to false. This is a legacy frontmatter flag that comes from the old `site-docs` repo, and which labels any destination that was rewritten in ~2018 to a standardized template. It disables the duplicate "connection modes" table that would otherwise show up in the boilerplate content at the end of the page. -- `hide-dossier`: defaults to false. When true, hides the "quick info" box at the top of a destination page. -- `hide-boilerplate`: defaults to false. When true, none of the content from `destination-footer.md` is appended to the destination page. -- `hide-cmodes`: defaults to false. A renaming of "rewrite" for more clarity, hides the connection modes table in the boilerplate. -- `hide-personas-partial`: defaults to false. When true, hides the section of content from `destination-footer.md` that talks about being able to receive personas data. -- `integration_type`: This is set in the `_config.yml` on three paths to add a noun (Source, Destination, or Warehouse) to the end of the title, and the end of the title tag in the html layout. It also controls the layout and icon for some of these. -- `source-type`: These are only used to supplement when a Cloud App in the sources path doesn't appear in the Config API list, and needs its type explicitly set. It runs some logic in the `cloud-app-note.md` to explain which cloud-apps are object vs event sources. - -#### Utility frontmatter -- `published`: defaults to true. Set this to "false" to prevent Jekyll from rendering an HTML page for this file. Good for when you're working on something in the repo but aren't ready to release it yet, and don't want to use a Draft PR. -- `hidden`: omits the file from the `sitemap.xml`, adds a `` to the top of the generated HTML file, and drops it from the convenience script for regenerating the nav. -- `hide-sidebar`: defaults to false. When true, hide the entire right-nav sidebar. Use with `hide-feedback` if you want to disable *all* feedback affordances. -- `hide-feedback`: defaults to false. When true, hide the feedback in both rnav and footer. Good for landing pages. -- `hide_toc`: hides the right-nav TOC that's generated from H2s. Also good for landing pages. -- `landing`: defaults to false. Use this to drop the noun set by `integration_type` from the tab title. -- `redirect_from`: Defaults to null. Takes an array of URLs from the frontmatter in a file, and generates a "stub" page at each URL at build-time. Each stub file redirects to the original file. Use the path from the root of the content directory, for example `/connections/destinations/catalog/` rather than `/docs/connections/destinations/catalog/`. **Note** We are mostly using NGINX redirects for SEO purposes. Approximately quarterly, we'll collect these and add them to NGINX. -- `seo-changefreq`: default: `weekly `. Use the values [in the sitemap spec](https://www.sitemaps.org/protocol.html#xmlTagDefinitions). - sets the `changefreq` tag in the sitemap.xml generator, which tells search crawlers how often to check back. -- `seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap - -## Navigation - -The navigation is built from static yml files, which allows us maximum control over what appears there and when. Find them in `src/_data/sidenav/` - -### Sidenav Icons -We have two neat icons that you can add to a bottom-level menu item to mark it with an icon. (If it's a folder/directory, the "expand" carat blocks this icon from appearing.) - -- `menu_icon: read-more` to show a book icon - use this to indicate that there's a lot more in this page than meets the eye -- `menu_icon: new-tab` to show an "external link" icon. Use this to indicate that the link in the sidenav is taking out outside the segment.com domain (for example to our API references hosted on Postman) - - -## Makefile commands - -- `dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild every time. -- `docs`: same as `make dev`, but for Laura's convenience. -- `build`: Builds the site docs. Used by CI to publish the docs to staging and production -- `catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key to be passed in env via PLATFORM_API_TOKEN. [Instructions here](https://github.com/segmentio/segment-docs/blob/master/contributors.md#refresh-the-segment-catalog). -- `sidenav`: Builds the side navs for 'main', 'legal', 'api', 'partners' and stores the output in `/src/_data/sidenav-auto/`. This output isn't used for the actual build. -- `typewriter`: pulls in the current state of the Docs tracking plan for implementing Segment tracking -- `seed`: copies all example data files out of the `_templates` directory and puts them in the `_data` directory. Useful if you don't have a way to set up an API key. -- `clean`: removes all build artifacts -- `clean-deps`: removes all downloaded `gems` and `node_modules` -- `deps`: installs the required `gems` and `node_modules` diff --git a/README.md b/README.md index 5074fc0a33..b4477ff3e6 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ In this article, find information about: - Contributing - A list of READMEs +- Code of conduct - License agreement ## Contributing @@ -33,6 +34,9 @@ For more information about contributing, see Contributing. - [Style Guide](styleguide.md) - [Developer Guide](devguide.md) +## Code of Conduct +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) + ## License Shield: [![CC BY 4.0][cc-by-shield]][cc-by] diff --git a/contributors.md b/contributors.md deleted file mode 100644 index 179b147827..0000000000 --- a/contributors.md +++ /dev/null @@ -1,218 +0,0 @@ -# Segment Docs Contributors Guide - -Thanks for helpin' out! We really appreciate it. - -![](guide-imgs/segment-sloth-heart.png) - -Here's what's here: - - -- [Contribute from the Github web UI](#contribute-from-the-github-web-ui) -- [Contribute using Git and Atom](#contribute-using-git-and-atom) - - [Making review edits in a PR](#making-review-edits-in-a-pr) -- [Contribute using git native commands](#contribute-using-git-native-commands) -- [Tips and tricks](#tips-and-tricks) - - [Adding links that open in a new window](#adding-links-that-open-in-a-new-window) - - [Escaping code snippets](#escaping-code-snippets) - - [Syntax highlighting](#syntax-highlighting) - - [Note Blocks](#note-blocks) - - [Redirect to a workspace](#redirect-to-a-workspace) -- [Set up on Mac using the Env script](#set-up-on-mac-using-the-env-script) -- [Refresh the Segment catalog](#refresh-the-segment-catalog) - - [Set up to refresh the Segment catalog](#set-up-to-refresh-the-segment-catalog) - - - - -There are three ways to contribute. -- EASY: [Contribute from the Github web UI](#contribute-from-the-github-web-ui) - only use this when making small edits to existing text files -- INTERMEDIATE: [Contribute using Git and Atom](#contribute-using-git-and-atom) - use this for everything else -- ADVANCED: [Contribute using Git](#contribute-using-git-native-commands) - if you're a git nerd, you can use this method - -If you're changing how the docs render, adding files or changing images, you should use the intermediate or advanced options. - -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). - - -## Contribute from the Github web UI - -> **Use this method when making small edits to an existing file only.** -> Don’t use this when: -> - Editing more than one file at a time, -> - Adding or removing image files -> - Making edits that change how the docs or docs navigation works. -> -> In those cases, set up to [contribute using Atom], and run the docs locally to confirm that your changes work and render as expected. - -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” - ![](guide-imgs/github-edit-this-file.png) -2. Make your changes. -3. Scroll all the way to the bottom and make a note about your change. - ![](guide-imgs/github-commit.png) -4. Click **Propose file change**. -5. On the next screen, add a reviewer or two. - 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. -6. Once someone has reviewed and approved the change, merge the change. -7. Delete the branch once the change has been merged! - -**If changes are needed on your Github PR**: You (or they) can add Github "suggestions", which you can merge into your PR either in a batch, or 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. - -## Contribute using Git and Atom - -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! - -> ℹ️ **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/). - -1. Open Atom, and make sure the Git tool panel is open. - (Press `Ctrl + Shift + 9` to open or close it, or find it in the **Packages** menu in Atom.) -2. Switch to the `master` branch, and update/fetch master from within Atom, using the 🔄 Fetch button - ![](guide-imgs/atom-fetch.png) -3. Create a new branch from `master`. This is where you’ll commit your changes. - ![](guide-imgs/atom-new-branch.png) -4. Make your changes, and save the files you’ve changed. -5. Stage changes. This means you mark them as specific files that you want to save and check in. -6. Add a short commit message, and click **Commit to (branchname)**. This adds a save point to your branch. - ![](guide-imgs/atom-stage-commit-publish.png) - -7. Click **Publish** (or **Push**). - -8. Go to the [Segment-docs repo in Github](https://github.com/segmentio/segment-docs), and create new Pull Request (PR). - A pull request is how you ask to add your changes to the public version of the documentation. - If you recently pushed a new branch, Github will prompt you to open a PR by clicking the Compare & pull request button. - ![](guide-imgs/atom-github-new-pr.png) - (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.) -9. Open your Pull request. - 1. Add a good title that explains what your change does. - 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. - ![](guide-imgs/atom-github-pr-form.png) -10. Next, request a review or two. One person should be able to check for typos, the other for technical inaccuracies. - - If you’re making a large change, you should include someone from the Engineering or Product teams. - 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. - ![](guide-imgs/atom-github-reviewers.png) - - - -### Making review edits in a PR - -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! - -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! - -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! - - -## Contribute using git native commands - -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. - -1. Change to and update master (`git checkout master && git pull`) -2. Create a new branch from master (`git checkout -b my_new_branch`) -3. Make changes, save them. -4. Stage your changes (`git status` and `git add` the appropriate files) -5. Commit staged changes to your branch (`git commit`) -6. Push your branch and changes to the `segment-docs` repo (`git push`, `git push --set-upstream origin`) -7. Repeat steps 3-6 as needed. -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. -9. Request a review. The Codeowners should populate this, and if not you can tag someone on the docs team. -10. If changes are requested, repeat steps 3-6 as needed. -11. Once approved, merge and delete branch, delete branch locally. - - -## Tips and tricks - - -### Adding links that open in a new window - -Use the standard markdown format for links (ex: `[text](https://example.com)`). -To make a link open in a new tab append `[text](https://example.com){:target="_blank"}` to the end. - -### Escaping code snippets - -Certain code syntax is 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. - -``` -{% raw %} -To pass source name in the slack message, format it like so: `{{properties.sourceName}}` -{% endraw %} -``` - - -### Syntax highlighting - -We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉. -A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers). - -### Note Blocks -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`. - -You'd write a block like this: -```md -> warning "I am a warning" -> The body of the warning goes here. Premonition allows you to write any `Markdown` inside the block. -``` - -Notes *must* include a `[]` in the heading/title, even if it's empty. -You can see how to write them in the `formatguide.md`, and see how they render at [https://segment.com/docs/utils/formatguide/#alerts](https://segment.com/docs/utils/formatguide/#alerts). This section also includes instructions on when to use each one. - -### Redirect to a workspace -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 to the first workspace they have access to. (This does mean that it can go a bit wrong for users with access to multiple workspaces, however that's a small proportion of our users at this time.) - -https://app.segment.com/goto-my-workspace/destinations/catalog - - - -## Set up on Mac using the Env script - -Laura wrote a bash script to set up the environment for you on a Mac computer. If you're on another platform, please [email us](mailto:docs-feedback@segment.com) 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. - -> info "" -> You only need to run `make env` once! - -1. Set up your Github config so you have an SSH key on your laptop. -2. Clone this repo locally. -3. Open your Terminal app and navigate to where you cloned the docs repo. -4. Start by checking what directory you’re in, to make sure you’re in the `segment-docs` repo. - Type `pwd` (which means “print working directory”) to check. You should see something like `~/repos/segment-docs`. -5. Type `make env`. - The script first checks to see if you have [Brew](https://brew.sh) installed, and if you don’t, it installs it. It then runs more brew commands to download and install the software you need, including a bunch of really useful Atom packages. - - > **Heads up**! You’re going to need to enter your laptop password as part of this installation, but only once! - - Once the installer completes, you still need to do a few small configuration tasks. - -6. Open the Atom app, then click the **Atom** menu in the top left, and click **Install Shell Commands**. -7. Next, make sure you’re showing invisible characters. These are important for seeing weird formatting in the docs, and for troubleshooting markdown. - Go to **Preferences > Editor**, and scroll down to **Show Invisibles**. Make sure that’s checked! - ![](guides-img/show-invisibles.png) - - - - -## Refresh the Segment catalog - -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. - -To update the files, you run `make catalog` from your Terminal. Before you can do that, follow the instructions below: - -### Set up to refresh the Segment catalog - -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 allows the script to talk to the Segment APIs. - -1. If you don't already have one, sign up for a free Segment workspace. -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.** -2. Go to the workspace's **Settings > Access Management > Tokens** tab (or click [here](https://app.segment.com/goto-my-workspace/settings/access-management)). -3. Click **Create Token**. -4. Add a description (and specify that you're using it for docs purposes, so nobody revokes it accidentally). -5. Select **Workspace Member**, check **Source Admin**, and select one or all sources. You _can_ grant this token more privileges, but that's unnecessary. -5. Click **Create**. -6. Copy the token, and paste it after the equals sign (`=`) after "PLATFORM_API_TOKEN". -7. Save and close the file. - Before you run the make command you might need to type `env` and enter into Terminal, or otherwise restart your Terminal session. diff --git a/devguide-old.md b/devguide-old.md deleted file mode 100644 index ebf873c0e5..0000000000 --- a/devguide-old.md +++ /dev/null @@ -1,208 +0,0 @@ -# Segment Docs Dev guide - -The contents of this guide will help you get up and running with the Segment Docs local environment. - - - * 1. [Local development with `ruby` and `node`, without Config API](#LocaldevelopmentwithrubyandnodewithoutConfigAPI) -* 1. [Changing a DevCenter Destination's name](#ChangingaDevCenterDestinationsname) -* 2. [All about the Catalog script](#AllabouttheCatalogscript) - * 2.1. [Connection Modes in the Catalog script](#ConnectionModesintheCatalogscript) -* 3. [Developer information](#Developerinformation) - * 3.1. [Layouts](#Layouts) - * 3.2. [Config API + Catalog](#ConfigAPICatalog) - * 3.2.1. [API Key](#APIKey) - * 3.2.2. [Catalog Data + Doc Links](#CatalogDataDocLinks) - * 3.2.3. [Object Sources and Warehouses](#ObjectSourcesandWarehouses) - * 3.3. [Sidenav](#Sidenav) - * 3.4. [Breadcrumb](#Breadcrumb) - * 3.5. [Searching](#Searching) -* 4. [Testing](#Testing) - * 4.1. [Build Testing](#BuildTesting) - * 4.2. [Manual Testing](#ManualTesting) - - - - - - - -### 1. Local development with `ruby` and `node`, without Config API - -If using OSX: - * Install command line tools, `xcode-select --install` - * Install `Ruby` >= 2.3.0 https://www.ruby-lang.org/en/documentation/installation/ - * Ensure you're running `RubyGems` >= 2.5.0 by running `gem update --system` followed by `gem --version` - * Install `Bundler 2` with `gem install bundler` - * Install `Node` https://nodejs.org/en/download/ - * Install `Yarn` https://yarnpkg.com/en/docs/install - * Run server, `make dev` - * Visit http://localhost:4000/docs/ - -## 1. Changing a DevCenter Destination's name - -Occasionally, a destination will change names. This shouldn't be too difficult to handle, but make sure you do the following: -- Change the name of the file **to match destination's new slug** -- Check in the Partner Portal that the name change has appropriately filled out the `previousNames` field. There should be two (or more if this has aliases/many name changes). -- Add a `redirect_from` frontmatter item, with the url of the old doc. This funnels anyone arriving at the old page from a link outside the docs site to the page at the new name. -- Run a `make catalog` to pick up the name change. -- Run `make docs` and test that: - 1. The page shows up correctly at the url you specified using the new slug. - 2. The programmatic content appears (cmodes, settings, previous names) - 3. The redirect from the old page URL works. - -## 2. All about the Catalog script - -You run the Catalog update script by running `make catalog` from the docs repo. You, a person who is going to run the script, must first save a Segment token to an `.env` file locally, which is `gitignored` so we don’t check it in to gihub accidentally. - -Note: Old ConfigAPI tokens are not compatible with Public API. You'll need a new one if you want to use Public API. - -The script takes your token, inserts it into a request header, then contacts the API, downloads all the available metadata for destinations and sources. It then writes them into a series of yml files that the docs build can consume. (You can find these in `/src/_data/catalog/`) - -Note: We don’t currently (Feb '21) do this for warehouses (storage dests) because they were originally lumped in with destinations, and didn’t change often enough to be worth writing a script for. We just have a static `warehouses.yml` file instead. With the switch to Public API from ConfigAPI, we should change this. - -The script also “calculates” the values for the `connection-modes` table for destinations, but that’s a huge other headache. - -It also does some slugification and destination-name normalization, since our handling of dots and dashes hasn't been consistent over time. Finally, it checks to see if there’s a folder for each destination. If it finds a new one, the script makes a folder with a “stub” markdown file for that destination, and then adds a line for it to an "incompleteDocs.txt" file. (It doesn't check to see if it's already listed, just appends to the file.) - -### 2.1. Connection Modes in the Catalog script - -As part of the Dossiers project we worked on making the Connection Modes table more readable. Originally we were going to have per-page liquid run, but these modes don't change often so it would've added a lot of build time for very little benefit. Instead we pushed it into `catalog.js`. -Once the connection modes device and cloud arrays are set, we do a bunch of calculations, and add a text summary, a number which corresponds to that summary for easier programmatic writing, and a rough category. - -| Case | Summary | Type | Message | -| ---- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0 | No data available | none | No connection mode information available. | -| 1 | Both device, no cloud | device-only | accepts device-mode data from both Analytics.js and mobile sources. It does not accept data in cloud-mode. | -| 2 | AJS (web device) only | device-only | accepts device-mode data only from Analytics.js. | -| 3 | Mobile device mode only | device-only | accepts device-mode data only from a mobile source. | -| 4 | Accepts from all | all | accepts cloud-mode data from all Segment source types. It can accept device-mode data from both web and mobile sources. | -| 5 | All cloud types | cloud-only | accepts cloud-mode data from all Segment source types. It does not offer device-mode connections. | -| 6 | Mobile and Server cloud only | cloud-only | accepts data from any Segment mobile or server source in cloud mode. It does not accept data from a web source, and does not offer device-mode connections. | -| 7 | Web and mobile cloud only | cloud-only | accepts only cloud-mode data from web and mobile sources. | -| 8 | Mobile cloud only | cloud-only | accepts only cloud-mode data from mobile sources. | -| 9 | All cloud types, 1 device mode | mixed | accepts data in cloud-mode from all source types, and can accept data in device-mode from [Analytics.js or mobile] sources. | -| 10 | Web and mobile cloud, 1 device | mixed | accepts data in cloud-mode from web and mobile sources, and can accept data in device-mode from [Analytics.js or mobile] sources. | -| 11 | Mobile and server cloud, mobile device | mixed | accepts data in cloud-mode from mobile and server sources, and can accept data in device-mode from mobile sources. | - -## 3. Developer information - - -### 3.1. Layouts - -`default.html` is the base container through which all the individual other layouts are built to have the right title, seo, etc. The template inheritance is described in the diagram below. - -The `destination.html`, `source.html`, and `integration.html` templates contain the logic that runs the layouts for individual catalog pages. Storage/warehouses use the generic Integration right now because they don't need anything special. Set the layout in the Jekyll `_config.yml` file. - -```text -default.html - |- integration.html - |- destination.html - |- source.html - |- main.html - |- catalog.html - used for connections catalog pages only - |- home.html - for main landing page only - |- page.html - used for all pages outside Connections catalogs, without an explicit override - |- search.html - search results page only -``` - -### 3.2. Config API + Catalog - -The Segment Config API provides the data for the Source and Destination catalog pages. This happens on demand using `make catalog`, and the results are stored in the respective `_data/catalog` yml files. - -Warehouses.yml is currently built by hand, because warehouses have traditionally been considered a form of destination, so are not separated out in the Config API. - -#### 3.2.1. API Key -The Config API needs an API key to pull in the _latest_ catalog data and currently looks for one in the environment variable `PLATFORM_API_TOKEN`. This value is stored in a special file named `.env` that the appropriate scripts reference. You can what this file looks like by looking at `.env.example` - -If you want to interact with the Platform API, locally, first make sure you have run `make env`. This will create the appropriate `.env` file for you to work with - -**NOTE: Never check-in `.env` or remove it from `.gitignore`.** - -Once your local environment is configured, you then have two options to pull Platform API data: You can use the token in [`chamber`](https://github.com/segmentio/chamber) or you can create your own token. - - -##### Bring your own token - -You create your own token in the Segment App. You can use your own personal workspace, or if you have access to them, use [`segment-engineering`](https://app.segment.com/segment-engineering/settings/access-management) or [`segment_prod`](https://app.segment.com/segment_prod/settings/access-management). Go to **Settings > Access Management > Tokens**. -Any type of token will work, but you might want to limit it to a read-only token. If you're working in a shared workspace, make sure you label it so folks know what it's for and don't revoke it. - -Once you make a new token, paste the token value in the `.env` file like so: - -```text -PLATFORM_API_TOKEN=(token value here) -``` -You can now run `make catalog`! - -##### Chamber - -If you installed and have access to `chamber`, run the following command: - -```bash -$ aws-okta exec prod-privileged -- chamber read segment-docs platform_api_key -``` - -or for staging... - -```bash -$ aws-okta exec stage-privileged -- chamber read segment-docs platform_api_key -``` - -You should get something like this as the output of the command. -```bash -Key Value Version LastModified User -platform_api_key [REDACTED FOR DOCS] 2 08-05 10:24:55 arn:aws:sts::752180062774:assumed-role/production-write/bryan.mikaelian@segment.com -``` - -Edit the `.env` file (generated from `make env`) and replace the environment variable with the token above. `make catalog` should then work and you should see some output like this: - -```bash -$ make catalog -"Saving catalogs from Platform API..." -"Finished Destinations." -"Finished Sources." -"Done." -``` - - - -#### 3.2.2. Catalog Data + Doc Links -By default, the links on the catalog page and respective sidenavs attempt to automagically set hyperlinks, for actual doc file, at the path `connections/:type/:slug`. However, given the transitory state of Docs V2, these links might 404 since the respective doc might be in a different directory. - -#### 3.2.3. Object Sources and Warehouses -These two catalogs are hardcoded in the `_data` directory since the Config API does not expose these resources. - -### 3.3. Sidenav -The sidenav is managed by the files in `_data/sidenav/`. Depending on what section we are in determines the file used. We currently support up to 2 levels deep on a sidenav. - -### 3.4. Breadcrumb -The current breadcrumb is currently determined based on the `page.path` and the current page's `title` front-matter attribute. - -### 3.5. Searching -We're currently using Algolia, which uses `algolia.js` and `algolia.css`. The search indexing is managed on the Algolia site. - -## 4. Testing - -### 4.1. Build Testing -Currently the only automatic testing we perform is linting on the configuration yaml files to ensure proper the project will build. - -TODO: define rules for markdown linting and clean up linting errors -`npx remark ./src --use preset-lint-markdown-style-guide` - -### 4.2. Manual Testing - -There are also some manual testing scripts that you can run to validate the build. - -1. Vale. Vale is a prose linter which you can run on-demand, or configure to work with Atom or other editors. - -2. `tests/redirects/redirects_bash`: used for validating a list of paths that we have nginx redirects for - -3. `tests/externalLinks/linkTester_bash`: used to validate that external links referenced in docs point to a validate endpoint - -4. `tests/imageSizes/getImageSizes.js`: used to get the 10 largest images in the repo. - -5. `npx mdspell 'src/**/*.md' -r --en-us`: used to validate spelling in docs, needs to be configured to add Segment terms. - -6. Included is the [Hyperlink](https://www.npmjs.com/package/hyperlink) NPM module. Run `bundle install` to install that, plus the tap-spot plugin for pretty output. To check all links on the site, prior to build, run `yarn run hyperlink ./_site/index.html --canonicalroot https://segment.com/docs -i -r --skip 0.0.0.0 | yarn run tap-spot`. This module checks hyper links, images, and anchor tags to ensure that everything linked internally resolves to a location. **TODO**: Add support for external links. diff --git a/docs.png b/docs.png deleted file mode 100644 index 35fd8e2882..0000000000 Binary files a/docs.png and /dev/null differ