Contribute to Open Source Docs via "Edit this page" on GitHub

Feb 10, 2022

Sarah

With open source projects, not only can you see the code, you can help edit and maintain the code, too!

Here’s an example of how you can contribute to Astro’s documentation, right from your browser!

Edit this page

On every page of the Astro documentation, there is a pencil icon and a link to “Edit this page” in the right hand sidebar.

Click this link! Your browser will navigate to the Astro Docs source repository on GitHub, taking you directly to the file for the page you’re viewing. To make a contribution to this file, select the pencil icon to edit. If you are not logged in, you will be prompted to log in.

If you are logged in, the pencil icon will take you to edit this file in your fork of this project. (If this is your first time editing a project, a fork will automatically be created in your own GitHub account. Yay! You now own a copy of the Astro docs!)

Propose Changes

After clicking the pencil icon to edit that file, you will be greeted by a banner reminding you that you do not have permission to make changes directly to the file. Instead, you will make changes in your own copy of the documents, then submit a pull request to the original project.

In edit mode, you can flip between typing Markdown source code and previewing those changes on the page.

Once you have made changes, use the “Propose Changes” button at the bottom of the page to submit your new version of the page to the Open Source project for consideration. Be sure to include a short but descriptive title of what you changed, and optionally, a longer description. This could be a more thorough explanation of what you changed, or why you believe the change was necessary or appropriate.

After “proposing changes,” you’ll still have two more steps to go (and two more chances to back out!) in order to create a pull request. So there’s absolutely no risk in going this far!

Create a pull request

Next, you’ll be taken to a page that performs a check to make sure that your changes are able to be merged, without conflict, into the open source repository. It’s at this point that you’ll click the submit button to “create a pull request” (PR)… but this is only the button that takes you to another page where you’ll have a chance to edit your PRs title and description before actually opening it (sending your proposed changes to the original repository).

It’s totally safe to click here! You’ve still got one more chance to back out!

The next page you’ll reach will again confirm that your changes can be merged without creating a conflict, and will allow you to adjust your title and description as necessary. (This screenshot shows a pull request to one of my own repositories this time, instead of the Astro docs.)

⚠️ When you click “Create a pull request” on this screen, now you actually create a pull request! This one counts!

Here, you can leave a comment in Markdown, and also preview your comment. So, if you’d like to add a more descriptive or elaborate description of your changes here, including lists, formatting, code blocks… feel free!

Also, there is a checkbox (selected by default) at the bottom, just before the submit button, for allowing edits by maintainers. This allows a maintainer of the project to accept your pull request while still making a change like fixing a typo or addressing a style issue. Perhaps the maintainer agrees with the idea of your proposted changes, but is unable to accept them exactly as you’ve written them. By checking this box, you’re allowing the maintainer to modify your changes so that they can still accept your pull request. Otherwise, if the maintainer cannot accept your changes exactly as you’ve proposed them, they will need to ask you to make changes and resubmit, or will be forced to deny your proposed changes entirely.

Once you are satisfied with the content of your pull request, click the button to submit (for realz!) and you’ll be taken to a confirmation screen that shows your “open” pull request, in the original repository.

Success!

Congratulations! Your contribution has left your hands! Your pull request joins all the other pull requests (shown in the upper left) to that project.

You can still add a follow up comment or decide to close the pull request at any time by revisiting this page. You can’t “delete” a pull request, but you can “close” it to let the maintainers of the project know that you are withdrawing your proposed changes. The pull request continues to exist, (and can even be re-opened with the press of a button!) but closed PRs are typically hidden out of sight behind a default filter that only shows “open” (unresolved) pull requests.

Also be aware that you will be automatically subscribed to receive notifications for any activity on this pull request. You can customize your notification preferences, but by default, you will receive an email when there is any activity on your request.

Continuing to Contribute

Your GitHub profile will now contain local copies, that you own, of the repositories to which you submitted changes. This means, you can easily revisit them at any time and contribute again and again!

You can continue to edit files on GitHub, or you can open these repositories however you prefer to work on them: locally on your machine, in an online development environment or code editor like Gitpod or CodeSandbox, or by using the handy ”.” (period key) shortcut while on GitHub to open github.dev for a VS Code editing experience instead of GitHub’s default individual file editing page.

⚠️ Avoid merge conflicts!

Remember how GitHub checked multiple times to make sure your changes could be merged into the original repository without any conflicts? Remember, the open source project probably has several people contributing to it, and it is changing all the time! (Even if you only work on your local copy every now and then.)

To make sure that any new changes you propose are compatible with the current version of the project, before you begin editing, you should always fetch upstream so that your project incorporates any new changes since the last time you contributed.

Navigating into one of your repositories should show you if your forked copy of the project is behind (i.e. not caught up with changes to) the original. There will also be an option to “fetch upstream” which will add all the new changes, and project commit history of the original project to your own.

Always do fetch upstream first, before starting to make changes to your local copy!

There is even a handy GitHub app called “Pull” that you can authorize to run automatically to perform this action at regular intervals so that you can avoid going a long time without fetching, and avoid issues of massive, even breaking, changes in the original project conflicting with what’s in your local copy. You should still fetch manually before each work session though, to catch any up-to-the-minute changes before you begin editing.

Any changes you make here are only local changes, contained in your repository. So feel free to experiment! You don’t have to send your changes back every time you make them… or, ever! You can work independently for as long as you want and make as many commits to your own project as you like. (Just remember to fetch upstream each time you begin again, to keep up-to-date with any upstream changes.)

When you do have new changes commited to your local fork of the project that you want to contribute back via a new pull request, go back to your repository’s main page. Instead of “fetching upstream,” this time you can “Contribute” back to the original project. (These options are next to each other on the page.)

“Contribute” will start the process for a brand new pull request, first by checking for merge conflicts, and then by allowing you to provide a good title and description for your changes. Your pull request, once opened, is attached to the original project for review, and the cycle begins again!

Thank you for contributing to open source!

Tags:

• docs
• open-source

React to XElement in Astro: sBird to xBird

Creating an Astro layout - screencast and transcript