Editing the Documentation and Creating a Pull Request on Github

I have seen a number of people complain about the documentation at https://home-assistant.io/ (HA site). Great news! Everyone can edit it and provide improvements to the documentation. Next thing I likely see is that people don’t know how to create a pull request on Github. Great news! Here is a tutorial on how to do it.

First go to https://github.com/ and sign up for an account. Its quick free and easy. If there is a need for a tutorial for this to please post that feedback below. Otherwise sign up and sign in.


In the upper right of most of the pages on the HA site there is a “Edit this page on GitHub” link.


When you click that link you will be brought to a new page with contents of the page you wanted to edit. In the upper right there is a pencil icon, click it to edit the page.


On the resulting page you can edit the text. Use the existing content and reference the existing page for figuring out how to edit the content. Usually the page just needs some tweaking so you don’t need to start over, just add on or delete some text. I have no idea how to create a page from scratch, but I have submitted 2-3 requests that are now in place with little issue. Don’t get hung up that it will be to complicated or you don’t know how to create the formatting, its easy.

If your making a small change don’t worry about the standards, follow the precedent on the page and make the correction. If your making a large change/new page be sure to read the devloper docs before getting started. Link Below.
https://developers.home-assistant.io/docs/en/documentation_standards.html

Here I provided some updates to the page (removing highlighted text). I provided a quick title for the pull request and added my reasoning below. When you are done, click “Propose file change”


On the next page, click “Create Pull Request”


On the next page add any additional comments and if related to a pull request on the actual Home Assistant code (not the web page) add the info and click “Create Pull Request”


Your Done!!! You just submitted your first pull request and contributed to improving HA!

If this is your first time submitting you likely will need to sign the CLA. This is easy to do and you will either brought straight to it or receive an e-mail to complete this step. Its as simple as reading and clicking another box.

From here you will get an e-mail stating that your pull request was submitted and it will identify some reviewers based on who has worked on the page in the past. You will continue to get e-mails with updates on the status as needed. Eventually you will get one that it has been merged and your changes will go live sometime after.

26 Likes

Great, I think that would be great to have in documentation

1 Like

I agree. This is just the sort of thing that we needed to have written up. Excellent work, @silvrr!

@Danielhiversen - I’m not sure if you realized the meta joke you just made. :laughing: Wouldn’t adding this to the documentation be roughly the same process?

@silvrr - Thanks so much for this!

2 Likes

Great example of why everyone needs to submit pull requests. In making this little tutorial I made a few tweaks to the yeelight component as shown above to provide the example. As I was paying more attention to making the tutorial than the config example there were errors in it. (spacing and and a missed colon :flushed:)

@LeeJS to save the day! He submitted a Pull Request and fixed the errors which should go live shortly. This just goes to show that we need everyone to be helping with the documentation. Also I need to focus on one thing at a time so I don’t make people frustrated with my config errors. (Sorry @LeeJS)

My pleasure!

This is great. I have lots of my own documents I’ve stored at home which I’ve used to record how I’ve setup some zwave specific devices so I’ll see about moving them here.

2 Likes

one picture is not loading

Thanks, I think this needs an update anyway. Added to my todo list.

1 Like

Might want to add what to do if you have clicked “Propose file change”, but then notice something needs to be changed (say I noticed a mistake in my edit), prior to clicking “Create pull request”.
In other words, go back to editing before creating the pull request.

OK, I updated the first post with the current workflow. I wasn’t getting this done so I did it as I was making an edit and noticed an issue.

Future items to add:

  1. Creating a github account?
  2. CLA signing process?
  3. Editing after you have clicked “Propose file change”

If anyone is going through the steps and wants to post the steps/screenshots I will either add them to my post or link to your post.