Contributing to documentation

Hey Rich,
following up on this in the other thread

I just realized that I made a PR for the JS scripting doc, which is not under „Documentation“ but „Add-on“.
Anyway, this is how it looks like when non-Github-experienced users want to do little changes to the documentation:
After clicking the „edit“ link you have to „fork“ (whatever that means…):

„commit changes“:

„Sign off and propose changes“:

„Create pull request“? Do I have to click on that one, too? I guess so…

Once more „Create pull request“?

Unfortunately I did not see a button to delete my own Test-PR

Creates a Github repository of your very own with the contents of the original repo. The original is “upstream” from your “fork”. You have full ownership and control over your fork. Changes you make there can be proposed to upstream in the form of a PR.

You will always be working out of your fork.

This makes the changes part of your fork.

This is a book keeping step to ensure that your changes are associated with you. We are still only working within your fork. You can make multiple commits at this stage if it’s a significant change.

This is where your changes get sent to upstream. Up to this point you’ve been only working in your own little playground (the fork) and upstream has no insight into what you’ve changed. It’s not until you create the Pull Request (PR) that they see the proposed changes.

This is where you create the “letter” that the maintainers see. Give your PR a meaningful name and describe what you changed and why. This is the first thing the upstream maintainers will see.

Navigate to the upstream repo, click on PRs, click on your PR, and you should have the option to “close” it. Once closed the PR is done. There is no deleting a PR. All work ever done, even work never approved, gets saved.

I’d have to look to see how to rebaseline your fork to remove your changes. It can be easier to create a branch first but for simple documentation updates that’s overkill. It might be as simple as clicking “sync fork”. If worse comes to worst you can delete the fork. Navigate to your repo, click the “settings” and under “General Settings” there is a “Danger Zone” section where you can delete the fork.

Note, there are lots of tutorials on the wide web and on this forum. The most comprehensive is [Wiki] How to contribute to the openHAB Documentation

Note, once you’ve created your Github account and your fork you do not need to create that again.

Ok, thanks for your explanation. I just raised it as I was irritated by your statement „all the rest of that gets handled when you click on that link at the bottom of the page“. That sound to me too far away from my experience above.

What I meant was the web page that comes up walks your through all these steps. Even without a tutorial to follow and without understanding what everything means you managed to successfully submit a PR following the prompts on the page that came up. That’s all I meant. I never meant it was a one step process.

1 Like

It all seems strange and scary the first time you do this (just like walking and cycling). Once you know how this works you can also contribute to 1000s of other open source projects on GitHub. :slight_smile: