At the end of a doc page there is a link to GitHub whichs leads me to the original file for the doc. I understand, that i need a GitHub user to be able to login. After logging in, i get a page like shown below:
Having quite no knowledge about how to use GitHub, reading about “fork”, “issues” and “pull requests” i have a simple question:
Do i have to edit the file, give a short and a long reason for the change ab press “Propose changes” and that’s it? So someone else with write access will have a look an possibly commits the change?
Is basically a copy of the openhab-docs repository where you can make your changes.
This is where your edit will be saved (at least temporary)
This is the next step.
You edit the file (remember it is stored in your “fork”) and then you request a pull to the original files.
There a maintainer (in fact that will mostly be me for the docs) can check your changes and suggest improvements and additions.
At some point the Pull request will be accepted and get merged into the main docs.
One thing ahead:
When you will open your pull request you may see a red x saying your dco check has failed.
Don’T worry about that too mich. We can solve it and it is no veto against your pull request.
I have written down what happens (and how to solve it before) here.
But thats not mandatory to understand for a first pull request.
There is a start to some of that at How to file an Issue. I can make it a Wiki or feel free to copy as much or as little as is useful. It mostly focuses on creating an issue and a small PR through the web page (like OP’s original work flow).
When I try to help people I usually make a distinction between small and easy changes and big changes. I direct them to the tutorial I linked to for small easy edits. For bigger stuff I always say “open an issue first” and then go from there.
I just had a look at that and feel it to be a bit overwelming for documentation changes. Looking at a doc page and realizing a typo f.e., i just have to use the link to GitHub at the end of every doc page, (after logging in) may change the doc file and propose the change.
Because i never did this before, I wondered about the “fork” and if i’d have to care about that fork having been created. And i don’t know what will happen after pressing “propose change”. @Confectrician: yes, i am interessted in .
So for the correction of the documentation, i didn’t need to know more. I did not have to create an issue etc.
What i feel atm is, that there should be a very simple explanation of the doc changing process and an other (like the one from Rich) to file issues and follow them up to a solution. Maybe i am wrong, though!
i strongly suggest ALL official documentation appear on the website. Many times for openHABian, for example, users are expected to read the README.md file on gitHub. the Docker Hub docs should also be replicated in the website.
The preceding is only my personal opinion and an attempt to help newcomers.
If the sign off rule exists because of the way that openHAB is licensed then so be it, but if it’s a hang-over because the code has to be signed, but not strictly the docs, then perhaps this requirement could be reviewed?
I don’t intend to argue about it at all - I perfectly respect the decision and rules: just putting it out there why I currently cannot contribute to documentation.
The docs are licensed and maintained under the same Organisation as the code is.
And the Organisation decided to require a sign-off at some point.
I would say that the docs repo handles already most of the sign of statement exceptions within the Organisation.
But with my current information level i am not able to omit the sign-off statement completely for large edits.
Maybe you could finde someone who is willing to transfer improvements from here to github, but that’s of course some effort that would have to be made on top.
For anyone who reads this thread, don’t sweat it, just do it, use the web interface the first time, follow the directions and Jerome will help you!!! He helped me make my first pull request and I screwed it up and he was super patient with me and taught me how to do it