
# How to Contribute to the Gatsby Repository

#### Learn how to contribute code to the open source project Gatsby

**In Gatsby all projects are packages including Gatsby, plugins, and themes:** It's a [monorepo](https://en.wikipedia.org/wiki/Monorepo) managed with [Lerna](https://lerna.js.org/).

At the end of this tutorial, **you'll have a working local setup** where you can test your changes to a Gatsby package.

Gatsby is one of the favorite static site generators right now. With more than 42.000 GitHub stars it's a major contributor to the [Jamstack concept](https://jamstack.org/). I would even say, one of their flagships.

The [source code lives on Github](https://github.com/gatsbyjs/gatsby) and everybody is welcome to contribute to the project.

If you encounter some problem while following this tutorial. Take a look at the troubleshooting section, at the end of this post.

_Let's start._

## Set Up the Gatsby Project

Go to the Gatsby GitHub project and [fork it](https://help.github.com/en/github/getting-started-with-github/fork-a-repo).

_The Gatsby project itself, all his packages, and the contributors documentation use Yarn as the package manager ([find out how to install Yarn](https://classic.yarnpkg.com/en/docs/install/))._

Clone the forked repo to your local machine.

```bash
# clone the fork
git clone --depth=1 https://github.com/<your-username>/gatsby.git

# go to gatsby
cd gatsby/

# install and build the projects
yarn run bootstrap

# check if everything works
yarn test
```

Configure the Git upstream.

```bash
# check your current remote configuration
git remote -v

# configure the original gatsby repo as your remote upstream
git remote add upstream https://github.com/gatsbyjs/gatsby.git

# check if the configuration has updated
git remote -v

# download objects and refs from the upstream
git fetch upstream

# integrate the upstream master into your local branch
git merge upstream/master
```

Create a branch.

```bash
# create the branch where you're going to work
git checkout -b <feature-or-bugfix>/<feature-or-bugfix-name>
```

Create a symlink to a Gatsby package.

```bash
# change to the package directory (in this case a gatsby plugin)
cd packages/gatsby-transformer-remark/

# create the global symlink to the package
yarn link

# start watching the package files for changes
yarn watch
```

Add `` console.warn(`HELLO_GATSBY_DEVELOPMENT`) `` to `gatsby-transformer-remark`.

```javascript
// in packages/gatsby-transformer-remark/src/on-node-create.js:16

// code...

const { createNode, createParentChildLink } = actions;

// Add the next line before the if:
console.warn(`HELLO_GATSBY_DEVELOPMENT`);

// We only care about markdown content.
if (
  node.internal.mediaType !== `text/markdown` &&
  node.internal.mediaType !== `text/x-markdown`
) {
  return {};
}

// more code...
```

## Set Up a Gatsby Site

Now you're going to set up a Gatsby site as an end-user would do. This will help you to test the changes you're doing to the Gatsby project.

_Gatsby CLI generated sites and the Gatsby end-user documentation use npm._

Open a new terminal and create a Gatsby test site.

```bash
# install gatsby-cli
npm i -g gatsby-cli

# go back to your workspace directory
cd ../../../

# create a new gatsby site
gatsby new gatsby-test-site

# change directory into site folder
cd gatsby-test-site/
```

Link the Gatsby plugin inside `gatsby-test-site`.

```bash
# link the local package (the package will not appear in your package.json)
npm link gatsby-transformer-remark
```

Add configuration to `gatsby-config.js`.

```js
// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      // CommonMark mode (default: true)
      commonmark: true,
      // Footnotes mode (default: true)
      footnotes: true,
      // Pedantic mode (default: true)
      pedantic: true,
      // GitHub Flavored Markdown mode (default: true)
      gfm: true,
      // Plugins configs
      plugins: []
    }
  }
];
```

Start the `gatsby-test-site`.

```bash
gatsby develop
```

You should see the `HELLO_GATSBY_DEVELOPMENT` in the terminal.

![Gatsby CLI develop command output](/images/posts/gatsby-develop-cli-output.png)

**Congratulations! You have a working Gatsby environment. And you can start contributing to the open source project right now.**

Find first-time friendly issues on the [Gatsby project issues tab](https://github.com/gatsbyjs/gatsby/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

You got questions or want to start a conversation? Contact me on [Twitter](https://twitter.com/rbelow_) or [GitHub](https://github.com/rbelow)!

**By the way: don't forget to test and lint the package you're changing.**

```bash
# from the root of the gatsby repo
yarn jest gatsby-transformer-remark

yarn lint
```

_Happy coding!_

## Troubleshooting

### gatsby develop throws errors

When executing `gatsby develop` on your `gatsby-test-site` throws errors:

- Clean up the Gatsby cache with `gatsby clean`. If the problem persists remove `node_modules`, and `package-lock.json` and do `npm i`

To make it easier for the future add a script to your `package.json`.

```json
{
  "scripts": {
    "clean:npm": "rm -rf ./node_modules/ && rm ./package-lock.json"
  }
}
```

### Error: ENOSPC: System limit for number of file watchers reached

If you get a `System limit for number of file watchers reached` error, while watching files on a Linux distribution:

- [Increase the file watch limit of your OS](https://github.com/guard/listen/wiki/Increasing-the-amount-of-inotify-watchers)

### Software Versions

These are the software versions used for this tutorial:

- Gatsby: 2.19.32
- Gatsby CLI: 2.8.27
- gatsby-transformer-remark: 2.6.55
- Node.js: 12.16.1
- npm: 6.13.4

---

Kudos for learning with this tutorial.

**_Follow me on [GitHub](https://github.com/rbelow) or [Twitter]._**

[twitter]: https://twitter.com/rbelow_ 'Twitter'

_If for some casual the indications did not work for you; [drop me a line with the infringing points](mailto:hello@rubenbelow.com?subject=Infringing%20Point).
I'll update the post correspondingly._

## References

- [Setting up Your Local Dev Environment](https://www.gatsbyjs.org/contributing/setting-up-your-local-dev-environment/#add-tests)
- [Debugging the Build Process](https://www.gatsbyjs.org/docs/debugging-the-build-process/#chrome-devtools-for-node)
- [Adding Markdown Pages](https://www.gatsbyjs.org/docs/adding-markdown-pages/)
- [gatsby-dev-cli Usage Example](https://www.youtube.com/watch?v=D0SwX1MSuas)
- [Configuring a Remote for a Fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork)
- [Syncing a Fork](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)

## More Posts

- [Routing an External Registered Apex Domain to an AWS S3 Bucket](/posts/third-party-apex-domain-aws-s3-static-website-routing)
- [Welcome](/posts/welcome)


Learn how to contribute to the Gatsby open source monorepo on GitHub

How to Contribute to the Gatsby Repository


# Routing an External Registered Apex Domain to an AWS S3 Bucket

Your website will be accessible with HTTP. To access it with HTTPS do these three extra steps:

1. [Create a certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) with the AWS Certificate Manager for your domain
2. [Create an AWS CloudFront distribution](https://aws.amazon.com/premiumsupport/knowledge-center/cloudfront-serve-static-website/) for your "root" S3 bucket. Associate the certificate to it
3. Point the `ALIAS` record of your apex domain to the new CloudFront distribution

## How to Point a Naked Domain - Not Registered with Route 53 - to an AWS S3 Hosted Static Website

_So people can access your website through `example.com` instead of `www.example.com`._

In this post, we're going to connect an
[apex domain](https://www.quora.com/What-is-an-apex-domain) with an AWS S3 hosted website. The naked domain is bought in a domain name registrar other than AWS Route 53. In this case [OVH](https://www.ovh.com/).
**For other registrars the steps are similar.**

Apex domains, generally, cannot
make use of `CNAME` records. Allowed are `A` or `AAAA` records, pointing to
static IPs. This makes it harder to use our naked domain for
our website: `example.com`. This is because of the dynamic nature of AWS S3 instances. They expose a
subdomain endpoint, so they can route the internal traffic with freedom.

_Let's start._

### Copy your current zone file

[Log in to your OVH account](https://www.ovh.com/auth/), go to: _Domains > DNS zone_, and reduce the `TTL` (Time to Live).
The authoritative name servers cache will expire faster now. This is good because we're going to change the `NS` (Name Server) records.

Now click on: _DNS zone > Change in text format_, and copy your RRs (Resource Records).

It should look like:

```
$TTL 3600
@	IN SOA dns18.ovh.net. tech.ovh.net. (2019112215 86400 3600 3600000 300)
                          IN NS     dns18.ovh.net.
                          IN NS     ns18.ovh.net.
                          IN MX     100 mx3.mail.ovh.net.
                          IN MX     1 mx1.mail.ovh.net.
                          IN MX     5 mx2.mail.ovh.net.
                          IN A      ???
                          IN AAAA   ???
                          IN TXT    "1|www.rubenbelow.com"
                      600 IN TXT    "v=spf1 include:mx.ovh.com ~all"
_autodiscover._tcp        IN SRV    0 0 443 mailconfig.ovh.net.
_imaps._tcp               IN SRV    0 0 993 ssl0.ovh.net.
_submission._tcp          IN SRV    0 0 465 ssl0.ovh.net.
autoconfig                IN CNAME  mailconfig.ovh.net.
autodiscover              IN CNAME  mailconfig.ovh.net.
ftp                       IN CNAME  rubenbelow.com.
imap                      IN CNAME  ssl0.ovh.net.
mail                      IN CNAME  ssl0.ovh.net.
pop3                      IN CNAME  ssl0.ovh.net.
smtp                      IN CNAME  ssl0.ovh.net.
www                       IN CNAME  ???
```

_Some values are replaced with: ???_

In the next step, we're going to import our entries in AWS Route 53. Before, let us delete some entries.

Records to delete:

```
IN NS     dns18.ovh.net.
IN NS     ns18.ovh.net.
...
IN A      ???
IN AAAA   ???
...
www                       IN CNAME  ???
```

### Create an AWS Route 53 Hosted Zone

[Log in to your AWS console](https://console.aws.amazon.com/route53/home#hosted-zones:), go to Route 53,
and click on: _Create Hosted Zone_. As: _Domain Name_, use the name of your apex domain: `example.com`.

### Modify your DNS file SOA record

Before starting with the next step we need to change the `SOA` (Start of Authority) record to match
the new one.

**Change:**

```
@	IN SOA dns18.ovh.net. tech.ovh.net. (2019112215 86400 3600 3600000 300)
```

**To the `SOA` record in your new Hosted Zone.**

The entry should now be like:

```
@	IN SOA ns-289.awsdns-36.com. awsdns-hostmaster.amazon.com. 1 7200 900 1209600 86400
```

### Import your DNS file into Route 53

Now that we have a fresh hosted zone we'll import the `RR` records we exported from OVH.

**Do not import the previously deleted `NS`, `A`, and `AAAA` records!**

1. Click on your new Hosted Zone: `example.com` (you'll see a list of RRs)
2. Click on: _Import Zone File_
3. Paste your previously exported `DNS` records
4. Import your `DNS` records

If you get: _"Error parsing zone file: One resource cannot have multiple distinct TTL values"_. Delete the mismatching
`TTL` from the zone file.

From:

```
600 IN TXT    "v=spf1 include:mx.ovh.com ~all"
```

To:

```
IN TXT    "v=spf1 include:mx.ovh.com ~all"
```

### Add an ALIAS record

_So far, so good._

Now we add an `A` `ALIAS` record for the naked domain; `example.com` pointing to our AWS S3 bucket.

![AWS Route 53 A record with ALIAS](/images/posts/aws-route-53-alias-example.png)

_It should be like this but with an S3 bucket URL instead of a CloudFront URL_

**Do the same now with an `AAAA` record.**

### Add a CNAME record

Add a `CNAME` record for your `www` subdomain pointing to your apex domain: `example.com`.

![AWS Route 53 CNAME record pointing to apex domain](/images/posts/aws-route-53-cname-example.png)

_It should be like this_

### Get your new NS entries

Get the values of your `NS` entry. We're going to use them at OVH in the next step.

They should be like:

```
ns-289.awsdns-36.com.
ns-1715.awsdns-22.co.uk.
ns-1241.awsdns-27.org.
ns-740.awsdns-28.net.
```

### Add your new AWS NS values to your domains registrar

In your OVH account go to: _DNS servers_

1. Delete the old OVH `NS` records
2. Add your new AWS `NS` records

_Good to go._

### Troubleshooting

The changes will take some time to propagate (sometimes up to 24h). We can check
the state of the DNS (Domain Name Server) update on:

- [Zonemaster](https://www.zonemaster.net/domain_check)
- [MXToolBox](https://mxtoolbox.com/dnscheck.aspx)
- [DNS Checker](https://dnschecker.org/)

If the DNS update is done but you cannot access `example.com` through your computer, it could be that your ISP (Internet Service Provider) still
did not update their RR cache. In this case, you should be able to [access your website through a VPN](https://www.hidemyass.com/en-eu/proxy).

---

Thanks for learning with this tutorial.

**_Follow me on [GitHub](https://github.com/rbelow)._**

_If for some casual the indications did not work for you; don't mind to [drop me a line with the infringing points](mailto:hello@rubenbelow.com?subject=Infringing%20Point).
I'll update the post correspondingly._

## References

- [Migrating DNS](https://docs.aws.amazon.com/de_de/Route53/latest/DeveloperGuide/MigratingDNS.html)
- [Migrate DNS Domain in Use](https://docs.aws.amazon.com/de_de/Route53/latest/DeveloperGuide/migrate-dns-domain-in-use.html)
- [How to Resolve Error in AWS Route 53 Import Zone File](https://stackoverflow.com/questions/34478249/how-to-resolve-error-in-aws-route-53-import-zone-file-error-multiple-distinc)

## More Posts

- [Welcome](/posts/welcome)


A warm welcome to Rubén Below's blog. I plan to actualize this section of rubenbelow.com regularly with useful tutorials, opinion posts about actual technological...

Routing an External Registered Apex Domain to an AWS S3 Bucket


# Welcome

**A warm welcome to Rubén Below's blog.**

I plan to actualize this section of [rubenbelow.com](/) regularly with
useful tutorials, opinion posts about [actual technological developments](https://www2.deloitte.com/us/en/pages/technology-media-and-telecommunications/articles/technology-industry-outlook.html),
some thoughts about the world, and lived experiences as a professional
in the [software and digital industry](https://www.mckinsey.com/business-functions/mckinsey-digital/our-insights/competing-in-a-digital-world-four-lessons-from-the-software-industry).

Expect also to read about startups, and business (some of my passions).

I'm very interested in your feedback and ideas. Also if you have a special
interest in a topic you want I write about, please [contact me](/imprint).

Welcome to this little space in the vast ocean of the internet. I'll
work to deliver real value for you; through the written word.

_Feel at home._

Greetings, Rubén!
