From f298882078f57e0353a70e34d0441140c06c45e7 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Thu, 1 Oct 2020 11:27:27 -0700 Subject: [PATCH] add contributing/development.md (#15806) * add contributing/development.md * Update CONTRIBUTING.md Co-authored-by: Sarah Schneider * Update contributing/development.md Co-authored-by: Sarah Schneider * Update contributing/development.md Co-authored-by: Sarah Schneider * Update contributing/development.md Co-authored-by: Sarah Schneider * Update contributing/development.md Co-authored-by: Sarah Schneider * Update contributing/development.md Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> * Update contributing/development.md Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> * cross-link to various liquid docs Co-authored-by: Sarah Schneider Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> --- CONTRIBUTING.md | 2 + README.md | 62 +-------------------- contributing/{readme.md => README.md} | 1 + contributing/development.md | 77 +++++++++++++++++++++++++++ includes/liquid-tags/README.md | 5 +- lib/liquid-tags/README.md | 2 + 6 files changed, 88 insertions(+), 61 deletions(-) rename contributing/{readme.md => README.md} (93%) create mode 100644 contributing/development.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17ed340a958a..71a7a92ff3c9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,6 +85,8 @@ You can use the GitHub user interface :pencil2: for some small changes, like fix ## Working in the github/docs repository Here's some information that might be helpful while working on a Docs PR: +- [Development](/contributing/development.md) - This short guide describes how to get this app running on your local machine. + - [Content markup reference](/contributing/content-markup-reference.md) - All of our content is written in GitHub-flavored Markdown, with some additional enhancements. - [Content style guide for GitHub Docs](/contributing/content-style-guide.md) - This guide covers GitHub-specific information about how we style our content and images. It also links to the resources we use for general style guidelines. diff --git a/README.md b/README.md index b5e314001f63..66fa37e4e690 100644 --- a/README.md +++ b/README.md @@ -7,16 +7,12 @@ GitHub's Docs team works on pre-production content in a private repo that regula In this article: - [Contributing](#contributing) - [READMEs](#readmes) -- [Developing](#developing) -- [Site structure](#site-structure) -- [Error handling](#error-handling) -- [Search](#search) - [License](#license) - [Contributors ✨](#contributors-) ## Contributing -:memo: To find out how you can best contribute to GitHub's product documentation, see [CONTRIBUTING.md](/CONTRIBUTING.md). +:memo: To find out how you can best contribute to GitHub's product documentation, see the [CONTRIBUTING](/CONTRIBUTING.md) guide. :mega: If you'd like help troubleshooting a PR, have a great new idea, or want to share something amazing you've learned in our docs, join us in [discussions](https://github.com/github/docs/discussions). @@ -31,6 +27,7 @@ In this article: In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail: - [content/README.md](content/README.md) +- [contributing/README.md](contributing/README.md) - [data/README.md](data/README.md) - [data/reusables/README.md](data/reusables/README.md) - [data/variables/README.md](data/variables/README.md) @@ -44,61 +41,6 @@ In addition to the README you're reading right now, this repo includes other REA - [stylesheets/README.md](stylesheets/README.md) - [tests/README.md](tests/README.md) -## Developing - -This site is powered by Node.js! :turtle: :rocket: - -You'll need **Node.js v12** to run the site. If you're using nodenv (you can -run `nodenv version` to find out which Node.js version you're on), read the -[nodenv](#nodenv) section for instructions on switching to Node.js 12. If you're -not using nodenv, the best way to install Node.js is to -[download the LTS installer from nodejs.org](https://nodejs.org). - -Once you've installed Node.js, open up Terminal and run the following: - -```sh -git clone https://github.com/github/docs-internal -cd docs-internal -npm install -npm start -``` - -You should now have a running server! Visit [localhost:4000](http://localhost:4000) in your browser. It will automatically restart as you make changes to site content. - -When you're ready to stop your local server, type CTRLc in your terminal window. - -## Site structure - -This site was originally written in [Jekyll](https://jekyllrb.com/) and later -[Nanoc](https://nanoc.ws/), both of which are Ruby static site generators. -This site is now a dynamic Node.js webserver powered by Express, using middleware -to add support for proper HTTP redirects, language header detection, and dynamic -content generation to support the various flavors of GitHub's product documenation, -like dotcom and GitHub Enterprise. For more context on why this change was made, -see the [new help.github.com](https://github.com/github/product-documentation/tree/master/new-docs-site#static-vs-dynamic) - proposal doc. - -The tech powering the site is now different, but many of the tried-and-true -authoring conventions of the original Jekyll site have been preserved: - -- Content is written in Markdown files which live in the `content` directory. -- Content can use the Liquid templating language. -- Files in the `data` directory are available to templates via the `{% data %}` tag. -- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter). -- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported. - -See the [Content README](content) for more info. - -## Error handling - -Errors generated from requests will be sent to Sentry via `middlware/handle-errors.js`, and the `lib/failbot.js` client. This is a lightweight wrapper for sending exceptions to GitHub's Sentry instance. - -## Search - -This site's search functionality is powered by [Algolia](https://www.algolia.com), a third-party service. - -See [search.md](search.md) for details. - ## License The GitHub product documentation in the assets, content, and data folders are licensed under a [CC-BY license](content/LICENSE). diff --git a/contributing/readme.md b/contributing/README.md similarity index 93% rename from contributing/readme.md rename to contributing/README.md index a777103c090e..3c955c424497 100644 --- a/contributing/readme.md +++ b/contributing/README.md @@ -4,6 +4,7 @@ Check out our [contributing.md](../CONTRIBUTING.md) to see all the ways you can Here, you'll find additional information that might be helpful as you work on a pull request in this repo. +- [development](./development.md) - steps for getting this app running on your local machine - [content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site - [content style guide](./content-style-guide) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content - [deployments](./deployments.md) - how our staging and production environments work diff --git a/contributing/development.md b/contributing/development.md new file mode 100644 index 000000000000..70dc76ca654f --- /dev/null +++ b/contributing/development.md @@ -0,0 +1,77 @@ +# Development + +This document describes the process for running this application on your local computer. + +## Getting started + +This site is powered by Node.js! :sparkles: :turtle: :rocket: :sparkles: + +It runs on macOS, Windows, and Linux environments. + +You'll need **Node.js v12** to run the site. If you're using [`nodenv`](https://github.com/nodenv/nodenv), read the [`nodenv` docs](#nodenv) below for instructions on switching to Node.js 12. If you're not using `nodenv`, the best way to install Node.js is to [download the LTS installer from nodejs.org](https://nodejs.org). + +Once you've installed Node.js (which includes the popular `npm` package manager), open Terminal and run the following: + +```sh +git clone https://github.com/github/docs +cd docs +npm install +npm start +``` + +You should now have a running server! Visit [localhost:4000](http://localhost:4000) in your browser. It will automatically restart as you make changes to site content. + +When you're ready to stop your local server, type CTRLc in your terminal window. + +## Site structure + +This site was originally a Ruby on Rails web application. Some time later it was converted into a static site powered by [Jekyll](https://jekyllrb.com/). A few years after that it was migrated to [Nanoc](https://nanoc.ws/), another Ruby static site generator. + +Today it's a dynamic Node.js webserver powered by Express, using [middleware](../middleware/README.md) to support proper HTTP redirects, language header detection, and dynamic content generation to support the various flavors of GitHub's product documentation, like GitHub.com and GitHub Enterprise Server. + +The tooling for this site has changed over the years, but many of the tried-and-true authoring conventions of the original Jekyll site have been preserved: + +- Content is written in Markdown files, which live in the `content` directory. +- Content can use the [Liquid templating language](liquid-helpers.md). +- Files in the `data` directory are available to templates via the `{% data %}` tag. +- Markdown files can contain [frontmatter](https://jekyllrb.com/docs/front-matter). +- The [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll plugin behavior is supported. + +For more info about working with this site, check out these READMEs: + +- [content/README.md](../content/README.md) +- [contributing/README.md](../contributing/README.md) +- [data/README.md](../data/README.md) +- [data/reusables/README.md](../data/reusables/README.md) +- [data/variables/README.md](../data/variables/README.md) +- [includes/liquid-tags/README.md](../includes/liquid-tags/README.md) +- [includes/README.md](../includes/README.md) +- [javascripts/README.md](../javascripts/README.md) +- [layouts/README.md](../layouts/README.md) +- [lib/liquid-tags/README.md](../lib/liquid-tags/README.md) +- [middleware/README.md](../middleware/README.md) +- [script/README.md](../script/README.md) +- [stylesheets/README.md](../stylesheets/README.md) +- [tests/README.md](../tests/README.md) + +## `nodenv` + +[nodenv](https://github.com/nodenv/nodenv) is a tool for managing multiple Node.js versions on your local machine. It is **not required** to run this app, but you may already have it installed if you've worked on other projects that use Node.js. + +To install Node.js 12 and make it your default version, run this command: + +```sh +nodenv install 12.8.0 && nodenv global 12.8.0 +``` + +You may sometimes see a warning when running npm scripts with nodenv: + +```sh +npm WARN lifecycle The node binary used for scripts is [...] but npm is using [...] +``` + +This is due to nodenv's overriding behavior. To silence this harmless warning, the [nodenv docs](https://github.com/nodenv/nodenv/wiki/FAQ#npm-warning-about-mismatched-binaries) recommend running the following command from any directory: + +```sh +npm config set scripts-prepend-node-path auto +``` diff --git a/includes/liquid-tags/README.md b/includes/liquid-tags/README.md index d78bf2898ee3..17f71fb2d9ce 100644 --- a/includes/liquid-tags/README.md +++ b/includes/liquid-tags/README.md @@ -2,4 +2,7 @@ This directory contains templates for our custom Liquid tags. -For more details, see [lib/liquid-tags/README.md](../../lib/liquid-tags/README.md). \ No newline at end of file +See also: + +- [lib/liquid-tags/README.md](../../lib/liquid-tags/README.md) +- [contributing/liquid-helpers.md](../../contributing/liquid-helpers.md) \ No newline at end of file diff --git a/lib/liquid-tags/README.md b/lib/liquid-tags/README.md index 26b4cc96ffc7..c3ba12a2720a 100644 --- a/lib/liquid-tags/README.md +++ b/lib/liquid-tags/README.md @@ -1,5 +1,7 @@ # Liquid Tags +See also [contributing/liquid-helpers.md](../../contributing/liquid-helpers.md) + This directory contains custom Liquid tags for outputting dynamic content. These custom tags exist for a few reasons: - Content and styling should be separated. Writers should not be concerned with writing or maintaining stylistic markup.