Getting Started with Github and Gitbook

Overview

GitHub is a collaborative development platform for open-source software projects. It uses Git, a version control system, to track and log changes to the source code, and display that history front and center. The Yearn team also uses Github for transparent project planning, visible collaboration, and housing all of the team's documentation and projects. To reach Yearn's Github projects page just navigate to the Yearn repository and tap on Projects in the header as seen below:

  1. Yearn Finance Repository List
  2. Tap on Projects List Tab
  3. Tap on Docs to see a view of the documents projects page

The Yearn Documentation team takes advantage of GitHub's robust graphic user interface (GUI) for Git to open issues, leave comments and manage our content files. On Github you can create issues in a repository which can then be labeled with a particular tag and then assigned to someone. This issue will then pop up as a card on the Projects board which can be moved around based on its current status.

For more information on how to create an issue please visit Github Help - Creating an Issue. Additionally Yearn uses a simple Git branching model, where one party manages the master branch and reviews all changes before adding them, which is usually the job of one of the repo admins. To learn more about how git workflows work, including from a command line instead of a GUI like Github please see: GitHub Standard Fork & Pull Request Workflow.

Lost and have no idea how GitHub works? Check out this short video for a brief intro to GitHub. Feel free to peruse learn git branching for fundamental git concepts.

Yearn also uses Gitbook to present the information in our Github Docs Repository(AKA Repo) in a way accessible to the public which can be seen at the official Yearn Docs page.

Below are two clear guides to contributing via GitHub and Gitbook based on how much you believe you will be contributing.

Simple One-off Tasks

If you notice a typo or some small changes where you don't think setting up the documentation is worth the time to do so or you don't plan to be an ongoing contributor, just follow the below steps:

  1. Log into the GitHub website.
    a. Make sure you have a GitHub account and you’re logged in.
  2. Go to the Github website, and fork the repository (AKA repo) you are making a change to. For example, you may want to fork the Docs repository. You can do so by navigating to the repository you want to change and in the top-right corner of the page, click fork.

    a. Forking the repo creates your a version of the site on your GitHub so you can make changes without impacting the original project. To learn more about forking visit Github Forking Documentation
  3. In your forked repository, go to file or folder you want to change ensuring you adhere to the Writing Style Guide.
  • Edit File
    Once in the file, press the pen icon to edit content. This will enter edit mode within Github. Edit mode allows making and proposing new changes without overwriting existing content.
    Add File
    Once in the folder that represents proper page placement, press “Create new file”. This will add a new .md file in your own GitHub account. This allows you to propose the addition of your content without publishing it right away.
  1. Once file changes are complete, you'll need to commit your changes. To do this scroll to the bottom of the page to where it says "Commit changes," write a short description of your changes, and then click the 'commit changes' button.

  2. You will then be prompted to submit a Pull Request (PR). During that process you will be asked for an explanation of changes. This will help any reviewer understand what changes were made, so they can make a decision whether to publish it to the main branch/site.
  3. Once merged into your local repository Fill out Pull Request (PR) form by navigating back to the home page of your forked repository and tapping Pull Requests in order to submit your changes to the main Yearn Documentation "Trunk" which you forked from.
    a.
    b. Then tapping create Pull Request
    c. Lastly including enough information in the PR for the maintainers to adequately review.
  4. Review/Merge
    There might be feedback/changes on a PR. A reviewer can approve, request changes, or merge the edited file into the repo. Edits can be made with an open PR (often without leaving Github's website) and the PR will update automatically. Once happy, a reviewer will merge your work and it will be live on the site.

For Ongoing Contributions

Yearn uses Gitbook which leverages Github in order to organize our Documentation. In order to successfully contribute more than simple changes, reaching out to other Yearn contributors is always preferable to get an idea of what the team is working on. Feel free to reach out on Discord if you are having any trouble with the instructions below.

  1. Log into the GitHub website.
    a. Make sure you have a GitHub account and you’re logged in.
  2. Go to the Github website, and fork the Docs repository (AKA repo) you are making a change to. You can do so by navigating to the repository you want to change and in the top-right corner of the page, click fork, for more detailed instructions see the Simple One-off Tasks Guide listed above.
  3. Head on over to Gitbook and sign up for a free account. From there create a new space, give it a familiar name and ensure it is public.
  5. Once you have created a new space tap Integrations on the left sidebar and tap on the Github switch.
  6. You should be prompted with Link your GitHub repository where you can now select list all public repositories, in the list you can search your recently forked Yearn Docs repo, likely named docs for you.

  7. Tap that, select Sync "master" branch only if you are only working on the base branch or select a branch if you are working on translations as those live on other branches.For more information on how the Github branching model works seelearn git branching.
  8. Lastly for the prompt Which content should be used for the first synchronization ? select I write my content on GitHub. Give it some time to import and you should be all set!

Once fully imported you can now begin making edits right on the page you're on which you can Save and Merge when you are ready.


Once you are finished editing and are ready to merge these changes into the original Yearn master repo which you originally forked from. Go to your <your github name>/<your docs repo name> and Tap Create a Pull Request ensuring that the base repository is iearn-finance/docs and the head is <your github name>/<your docs repo name>. A Reviewer may then add some comments that require you to to submit your PR in order to ensure your additions look right before merging in. Fore more information regarding the PR and merge process see the guide above.

Confused? Reach out in Yearn Documentation Chat and someone will walk you through it step-by-step. If you think you can improve this guide feel free to submit a PR ;)

Select a repo