Thanks for the explanation of your workflow! It's insightful and interesting how we do many similar things, but in a different way.
Let me first walk you through the workflow we use, so we can see the similarities, and then figure out the next steps for the long-term.
If I wanted to edit something in the Fedora Docs, let's say the Fedora 28 Release Notes, I would do:
1) Fork the source repository and make a local copy. How:
I would click at "Fork" at the top-right corner which would create my own copy of the repository on the server.
In my terminal, I would clone my fork by:
Since I want to do changes for Fedora 28, I need to switch to the f28 branch. (A list of all branches is on the web UI we've already seen, at the right side. Branch names should be intuitive, so after seeing "f27, f28, master, etc.", I've guessed that f28 is the right one.)
$ git checkout f28
2) Do the edits in the local copy of the fork. How:
I would edit the .adoc files I want to edit. I would do multiple changes at once, that's fine. However, I would try to do changes of one "type" for a lack of a better term. For example, grammar edits. A complete rewrite of one page or a few related pages. Or adding some missing content. etc.
To preview my changes, I could use the instructions at the README.md which says I should run "./build.sh && ./preview.sh".
3) Commit and push the changes to the fork on the server. How:
After I'm done with the changes I would commit them (register the changes with the local copy of the fork):
$ git add .
$ git commit -m "describing my change here in about 8 words"
And then pushing the commits (applying the local changes to the fork on the server, so anyone can see it)
4) Send a PR. How:
Now I want to apply the changes I have in my fork on the server to the original repository. This is done by submitting a PR (pull-request, a request to the owner of the original repository to accept the changes I have made).
For that, I would open the original repository: https://pagure.io/fedora-docs/release-notes
, click on the "Pull Requests" tab, then on the blue "File Pull Request" drop-down, and select my fork and the branch I have edited. In this case that would be "[asamalik/release-notes] [f28]".
Now that I've selected the PR goes from asamalik/release-notes f28, I need to make sure it goes to the right branch in the target repository. I need to select "f28" in the dropdown that now probably says "master".
Now, I need to add a title and a description of what and why I've done.
I can also review the changes by clicking at "Files Changed" at the very bottom.
Finally, click "Create" and the PR has been submitted.
5) Someone needs to do a review. How:
Someone will check the changes and provides feedback. I can use the built-in discussion to discuss the changes with the reviewer. The reviewer either merges the PR, or asks for additional changes.
Good thing here is that I don't have to make my changes perfect at the first try. I can even ask for suggestions in the PR itself. And also, multiple different people can provide feedback. That's how we can scale across many people in the community.
6) Just sometimes, making additional changes. How:
I would go to the local copy of my fork, do the changes (step 2 above), and commit and push the changes (step 3 above). They will be applied automatically to the PR, because I have modified the same branch.
So, that's it.
Leslie, I have found three major differences between your workflow and the one I've just described:
1) The way we do the preview. We have provided tooling to preview the whole repository at once. That's useful for internal links, for example. Let me know if I can help with getting that work.
2) One change at a time vs. multiple changes at once. We do multiple changes at once, and provide feedback on all of them. It's always possible to say something like "I like the first five changes you've made, but I would do the last one differently". And then we can iterate. Which brings me to the third point:
3) We iterate. We don't expect things to be perfect at the first try. That's why we don't distinguish between a "review before submitting a PR" and the PR itself. We just submit the PR, get a feedback there, and if needed, we can do another set of changes based on the feedback.
This way, we don't need to send anything via email to individual people. Anyone in the community can provide feedback to the changes. And multiple people with the sufficient permissions can merge the changes.
What do you think? Does that make sense?
And as I said earlier, I'm happy to walk you through the whole process over a video call + screen share. We just need to figure out the best time as I'm in Europe, so it would probably be your morning and my evening.