Docs: new section for contributing #11812

marcysutton · 2019-02-16T00:08:07Z

Description

As per rfc/29, this PR introduces a major change to the Gatsby docs: a new /contributing section. I did a big find and replace to update all links, and there are also redirects for pages that moved.

This is a pretty large PR, and I welcome any and all feedback on the new structure and content. My only request is that we try to resolve any feedback quickly so that community PRs aren't working on outdated stuff.

Here's a screenshot of the new Contributing landing page:

Related Issues

Fixes #11803, Fixes #8847

Outstanding questions

Do we need to make any additional changes to CODEOWNERS?
I included a link to /contributing in the docs sidebar to ease the transition. Should the link use some kind of icon to distinguish that it takes the user away from the docs?
Should we add a new icon to the mobile nav (I didn't make any mobile changes in this PR)?
Any changes to the sidebar, specifically around accordions?

Subsequent related issues/stubs

Gatsby Governance Model: Docs: Gatsby Governance Model #11805
Triaging GitHub Issues: Docs: Triaging Github Issues #11810

Updated a bunch of paths of docs pages to their contributing counterparts, started adding new content.

calcsam

🎉 🎉 🎉 super exciting!

calcsam · 2019-02-16T09:01:32Z

docs/contributing/code-contributions.md

+- Double check your grammar and capitalise correctly
+- Commit and push to your fork
+- Create a pull request from your branch
+  - We recommend using a prefix of `docs`, e.g. `docs/your-change` or `docs-your-change`


Should we link to a canonical example PR, such as 9c21394#diff-bf544fce773d8a5381f64c37d48d9f12?

Yes! Great idea.

calcsam · 2019-02-16T09:15:27Z

docs/contributing/docs-contributions.md

+title: Docs Contributions
+---
+
+Gatsby, unsurprisingly, uses Gatsby for its documentation website. Thank you in advance and cheers for contributing to Gatsby documentation! It's people like you that make this community great!


It might be useful to highlight the number of people who have already done this, to reassure folks that this is a pretty common thing to do.

git log --pretty="format:%ae" docs/ yields 870 unique emails, so we could say, eg "As of February 2019, over 800 people have contributed to the Gatsby documentation" or whatever makes sense.

calcsam · 2019-02-16T09:17:47Z

docs/contributing/docs-contributions.md

+
+- [Gatsby Style Guide](/contributing/gatsby-style-guide/)
+- [Docs Templates](/contributing/docs-templates/)
+- [How to Write a Stub](/contributing/how-to-write-a-stub/)


Might be worth saying something along the lines of "after your first code contribution to the Gatsby repo (including documentation) you become eligible for a free shirt or pair of socks. See the swag page for more details!"

I added a section for it above these links!

calcsam · 2019-02-16T09:18:46Z

docs/contributing/how-to-pitch-gatsby.md

+
+- **Trusted:** Leverage the power of the latest web technologies including React, Webpack, GraphQL, modern JavaScript, and more. Get the best of both worlds—all the power and conveniences from React and its ecosystem with a really slick and responsive user experience.
+
+- **Flexible with BYOC (Bring your own content):** Build websites quickly and deploy them safely, no matter where your content lives. Load data from your CMS, static files, a database, or from multiple places at once. Your marketing team is happy because they can use the content management tools they’re familiar with (WordPress, Drupal, Contentful, Shopify).


We've moved to "content mesh" rather than "BYOC" framing

Good tip! I've updated it.

DSchau

Awesome stuff! Left some comments, but I'd be pretty happy to get this merged as-is.

DSchau · 2019-02-18T21:00:41Z

CODEOWNERS

@@ -1,5 +1,6 @@
 # All docs must be reviewed by the docs team.
 /docs/                                          @gatsbyjs/docs
+/contributing/                                  @gatsbyjs/docs


These are actually still under docs/ right? e.g. docs/contributing is the path to the new/updated content?

oh yes! The nested docs got me. Will revert!

docs/contributing/code-contributions.md

DSchau · 2019-02-18T21:06:06Z

docs/contributing/code-contributions.md

+
+## Making changes to the website
+
+If you want to make more changes to the website functionality or documentation, that is, change layout components or templates, add sections/pages, follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising


Suggested change

If you want to make more changes to the website functionality or documentation, that is, change layout components or templates, add sections/pages, follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising

If you want to make changes, improvements, or add new functionality to the website or documentation follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising

DSchau · 2019-02-18T21:07:41Z

docs/contributing/code-contributions.md

+To add a new blog post to the gatsbyjs.org blog:
+
+- Clone [the Gatsby repo](https://github.com/gatsbyjs/gatsby/) and navigate to `/www`
+- Run `yarn` to install all of the website's dependencies.


Not necessary, but maybe we link to a "Why Yarn?" section of the existing documentation here? It's a pretty common question as to why we require it.

DSchau · 2019-02-18T21:09:23Z

docs/contributing/code-contributions.md

+- Add your avatar image to `/docs/blog/avatars`
+- Add your name to `/docs/blog/author.yaml`
+- Add a new folder following the pattern `/docs/blog/yyyy-mm-dd-title`. Within this newly created folder add an `index.md` file.
+- Add `title`, `date`, `author`, and `tags` ([view existing tags](https://www.gatsbyjs.org/blog/tags/) or add a new one) to the frontmatter of your `index.md`. If you are cross posting your post you can add `canonicalLink` for SEO benefits. You can check the other blog posts in `/docs/blog` for examples.


Would it be valuable to have an example here? I've heard that the general term "frontmatter" isn't always known to people:

```md --- title: "Your Great Blog Post" date: YYYY-MM-DD author: John Doe tags: - awesome - post --- Your next great blog post awaits. ```

Great idea. I seem to remember it only allows a singular author, is that still true? Are tags optional?

I seem to remember it only allows a singular author, is that still true

Correct! But it would be fairly trivial to get multiple author support if we want that

Are tags optional

Yep! If a post doesn't have tags, we just render null. It's probably a best practice to add at least one though.

DSchau · 2019-02-18T21:17:06Z

docs/contributing/docs-contributions.md

+   use the file editor to edit and then preview your changes.
+2. Before committing the change and raising a PR in the UI, you need to make sure the PR meets the docs contribution criteria:
+   - Follow the standards outlined in the [Gatsby Style Guide](https://www.gatsbyjs.org/contributing/gatsby-style-guide/).
+   - If your PR did not come from an issue written by the core team, please add a comment to your PR that explains why it should be included in the docs, according to the [Docs Decision Tree](https://www.gatsbyjs.org/blog/2018-10-12-uptick-docs-contributions-hacktoberfest/#docs-decision-tree-and-examples).


Suggested change

- If your PR did not come from an issue written by the core team, please add a comment to your PR that explains why it should be included in the docs, according to the [Docs Decision Tree](https://www.gatsbyjs.org/blog/2018-10-12-uptick-docs-contributions-hacktoberfest/#docs-decision-tree-and-examples).

- If your PR did not come from an issue written by the core team, please add a comment to your PR that explains why it should be included in the docs, according to the [Docs Decision Tree](/blog/2018-10-12-uptick-docs-contributions-hacktoberfest/#docs-decision-tree-and-examples).

DSchau · 2019-02-18T21:17:10Z

docs/contributing/docs-contributions.md

+   [docs folder](https://github.com/gatsbyjs/gatsby/tree/master/docs) or [contributing folder](https://github.com/gatsbyjs/gatsby/tree/master/contributing) on GitHub and
+   use the file editor to edit and then preview your changes.
+2. Before committing the change and raising a PR in the UI, you need to make sure the PR meets the docs contribution criteria:
+   - Follow the standards outlined in the [Gatsby Style Guide](https://www.gatsbyjs.org/contributing/gatsby-style-guide/).


Suggested change

- Follow the standards outlined in the [Gatsby Style Guide](https://www.gatsbyjs.org/contributing/gatsby-style-guide/).

- Follow the standards outlined in the [Gatsby Style Guide](/contributing/gatsby-style-guide/).

docs/contributing/docs-contributions.md

DSchau · 2019-02-18T21:20:32Z

docs/contributing/how-to-contribute.md

+
+### Not sure how to start contributing?
+
+If you are worried or don't know where to start, be sure to check out our [where to participate](/contributing/where-to-participate/) page. You can also reach out to [Marcy Sutton (@marcysutton) on Twitter](https://twitter.com/marcysutton) or submit an issue and a maintainer can help give you guidance!


Might be worth mentioning pair programming sessions, or otherwise including the core team somehow more obviously in this offer? Or @jlengstorf?

Pair programming would be great to call out. I think it's helpful to give a direct point of contact, but I can see that becoming unsustainable. Probably not worth blocking over; we can adjust this later as we learn more about how this section is used.

That's an easy addition. I've included it on other pages, it makes sense to include it here too!

Co-Authored-By: marcysutton <[email protected]>

pieh · 2019-02-18T21:36:12Z

docs/contributing/code-contributions.md

@@ -0,0 +1,56 @@
+---
+title: Code Contributions


This document covers contributing content so I find the title misleading, but I don't really have better alternative

I can see that. The experience is pretty intertwined, I didn't see a clear way to separate them without repeating stuff....but happy to take suggestions

Ah here's why it's confusing: blog content and the website are all grouped into "code contributions". I will make a separate page for "blog and website contributions".

Edited to add my plans for making new pages!

pieh · 2019-02-18T21:38:48Z

docs/contributing/code-contributions.md

+
+## Making changes to the website
+
+If you want to make more changes to the website functionality or documentation, that is, change layout components or templates, add sections/pages, follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising


You don't need to make same setup (including gatsby-dev-cli, etc) to contribute to the website code. I know this was moved from current contributing section, but might be good opportunity to fix our mistake?

First 3 steps from below (contributing to the blog) is enough to get going:

Clone the Gatsby repo and navigate to /www

Run yarn to install all of the website's dependencies.

Run npm run develop to preview the blog at http://localhost:8000/blog.

And people can start hacking on website code.

m-allanson · 2019-02-18T22:36:12Z

This is looking great! On your unresolved questions:

Should we add a new icon to the mobile nav (I didn't make any mobile changes in this PR)?

I think we've tried to do this in the past, but had difficulty making enough space for an extra icon at smaller browser widths. @fk might have more background on this.

Another spot that runs out of space is the homepage - it's tricky to prevent the diagonal stripes from overlapping the main nav items at all browser widths.

I like * I included a link to /contributing in the docs sidebar to ease the transition, and maybe that's our answer for now? We could drop Contributing from the main nav in situations where there's no space for it, knowing it'll always be linked from the docs sidebar. I don't love this idea (I can see it being quite confusing), but it might be less awkward than working out how to squeeze in a new top level nav item for all window sizes. Maybe some other approach is better?

(Once a .org redesign is underway, the contributing section could be reinstated as a top level nav item for all pages and browser sizes. )

This change adds a new page for blog and website contributions

marcysutton · 2019-02-18T23:35:15Z

Thanks for all the feedback! I've incorporated your updates, including adding a page for "blog and website contributions". Hopefully it's good to go!

DSchau · 2019-02-18T23:38:28Z

docs/contributing/blog-and-website-contributions.md

@@ -2,6 +2,12 @@
 title: Blog and Website Contributions
 ---

+We wholeheartedly welcome contributions to the Gatsby blog and website! Instructions this page:


Instructions on these pages:

maybe?

oh yes! thanks 😅

marcysutton · 2019-02-19T19:22:38Z

All the feedback has been incorporated, can we merge this and the RFC?

DSchau

Let's do it. Thanks @marcysutton!

## Description As per [rfc/29](gatsbyjs/rfcs#29), this PR introduces a major change to the Gatsby docs: a new `/contributing` section. I did a big find and replace to update all links, and there are also redirects for pages that moved. This is a pretty large PR, and I welcome any and all feedback on the new structure and content. My only request is that we try to resolve any feedback quickly so that community PRs aren't working on outdated stuff. Here's a screenshot of the new Contributing landing page: ![contributing landing page](https://user-images.githubusercontent.com/1045233/52890806-938f8a00-313b-11e9-8645-c4991fc95fa3.png) ## Related Issues Fixes gatsbyjs#11803, Fixes gatsbyjs#8847 ## Outstanding questions - Do we need to make any additional changes to CODEOWNERS? - I included a link to `/contributing` in the docs sidebar to ease the transition. Should the link use some kind of icon to distinguish that it takes the user away from the docs? - Should we add a new icon to the mobile nav (I didn't make any mobile changes in this PR)? - Any changes to the sidebar, specifically around accordions? ## Subsequent related issues/stubs - Gatsby Governance Model: gatsbyjs#11805 - Triaging GitHub Issues: gatsbyjs#11810

Marcy Sutton and others added 9 commits February 15, 2019 15:38

initial move of contributing pages

f3c6bfd

fix: fix sidebar and move some images around

c027f16

chore: fix broken link

7c3af1d

Second pass on contributing docs!

e9d37d6

Updated a bunch of paths of docs pages to their contributing counterparts, started adding new content.

move contributing to the end of docs-links

23f6fa2

chore: disable accordion (expand top-level headers)

7da2db2

latest updates to contributing docs

bcfc233

deprioritize creator showcase

3954d82

convert github triage doc to stub

6c6481f

marcysutton requested a review from a team as a code owner February 16, 2019 00:08

marcysutton requested a review from a team February 16, 2019 00:08

marcysutton requested a review from a team as a code owner February 16, 2019 00:08

calcsam approved these changes Feb 16, 2019

View reviewed changes

calcsam reviewed Feb 16, 2019

View reviewed changes

incorporate feedback from Sam

6b66ff8

DSchau approved these changes Feb 18, 2019

View reviewed changes

Update docs/contributing/code-contributions.md

8693736

Co-Authored-By: marcysutton <[email protected]>

pieh reviewed Feb 18, 2019

View reviewed changes

Marcy Sutton added 5 commits February 18, 2019 15:06

fix links, codeowners

80515bf

reorganize code/docs/blog/website contributions

a4f96b8

This change adds a new page for blog and website contributions

add docker-compose instructions

da174b6

add details on contributing, incl. pairing

171dcf9

add tables of contents to docs

f638534

DSchau reviewed Feb 18, 2019

View reviewed changes

fix a typo

488facc

Marcy Sutton added 2 commits February 18, 2019 15:45

tweak blog/code page order, style

7b23b07

add more list items for readability

bb4228d

DSchau approved these changes Feb 19, 2019

View reviewed changes

DSchau merged commit d14137c into master Feb 19, 2019

DSchau deleted the docs/contributing-reorganization branch February 19, 2019 21:30

DSchau mentioned this pull request Feb 19, 2019

feat: add contributing docs re-organization gatsbyjs/rfcs#29

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: new section for contributing #11812

Docs: new section for contributing #11812

marcysutton commented Feb 16, 2019

calcsam left a comment

calcsam Feb 16, 2019

marcysutton Feb 18, 2019

calcsam Feb 16, 2019

calcsam Feb 16, 2019

marcysutton Feb 18, 2019

calcsam Feb 16, 2019

marcysutton Feb 18, 2019

DSchau left a comment

DSchau Feb 18, 2019

marcysutton Feb 18, 2019

DSchau Feb 18, 2019

DSchau Feb 18, 2019

DSchau Feb 18, 2019

marcysutton Feb 18, 2019

DSchau Feb 18, 2019

DSchau Feb 18, 2019

DSchau Feb 18, 2019

DSchau Feb 18, 2019 •

edited

Loading

jlengstorf Feb 18, 2019

marcysutton Feb 18, 2019

marcysutton Feb 18, 2019

pieh Feb 18, 2019

marcysutton Feb 18, 2019

marcysutton Feb 18, 2019 •

edited

Loading

pieh Feb 18, 2019

m-allanson commented Feb 18, 2019

marcysutton commented Feb 18, 2019

DSchau Feb 18, 2019

marcysutton Feb 18, 2019

marcysutton commented Feb 19, 2019

DSchau left a comment


		- Trusted: Leverage the power of the latest web technologies including React, Webpack, GraphQL, modern JavaScript, and more. Get the best of both worlds—all the power and conveniences from React and its ecosystem with a really slick and responsive user experience.

		- Flexible with BYOC (Bring your own content): Build websites quickly and deploy them safely, no matter where your content lives. Load data from your CMS, static files, a database, or from multiple places at once. Your marketing team is happy because they can use the content management tools they’re familiar with (WordPress, Drupal, Contentful, Shopify).


		## Making changes to the website

		If you want to make more changes to the website functionality or documentation, that is, change layout components or templates, add sections/pages, follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising

	If you want to make more changes to the website functionality or documentation, that is, change layout components or templates, add sections/pages, follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising
	If you want to make changes, improvements, or add new functionality to the website or documentation follow the steps for [setting up your local dev environment](/contributing/setting-up-your-local-dev-environment/). You can then spin up your own instance of the Gatsby website and make/preview your changes before raising

	- If your PR did not come from an issue written by the core team, please add a comment to your PR that explains why it should be included in the docs, according to the [Docs Decision Tree](https://www.gatsbyjs.org/blog/2018-10-12-uptick-docs-contributions-hacktoberfest/#docs-decision-tree-and-examples).
	- If your PR did not come from an issue written by the core team, please add a comment to your PR that explains why it should be included in the docs, according to the [Docs Decision Tree](/blog/2018-10-12-uptick-docs-contributions-hacktoberfest/#docs-decision-tree-and-examples).

	- Follow the standards outlined in the [Gatsby Style Guide](https://www.gatsbyjs.org/contributing/gatsby-style-guide/).
	- Follow the standards outlined in the [Gatsby Style Guide](/contributing/gatsby-style-guide/).


		### Not sure how to start contributing?

		If you are worried or don't know where to start, be sure to check out our [where to participate](/contributing/where-to-participate/) page. You can also reach out to [Marcy Sutton (@marcysutton) on Twitter](https://twitter.com/marcysutton) or submit an issue and a maintainer can help give you guidance!

Docs: new section for contributing #11812

Docs: new section for contributing #11812

Conversation

marcysutton commented Feb 16, 2019

Description

Related Issues

Outstanding questions

Subsequent related issues/stubs

calcsam left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DSchau left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DSchau Feb 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton Feb 18, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-allanson commented Feb 18, 2019

marcysutton commented Feb 18, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcysutton commented Feb 19, 2019

DSchau left a comment

Choose a reason for hiding this comment

DSchau Feb 18, 2019 •

edited

Loading

marcysutton Feb 18, 2019 •

edited

Loading