Wrong upstream in instructions?

[sfiquet]

Issue Description & Expected Outcome:
I think there's an issue with the instructions for setting up the upstream remote in Home-Contribute.md. It says:
git remote add upstream https://github.com/Chingu-cohorts/voyage-wiki.git

I'll admit I don't totally understand the process and that's why I'm asking. After comparing with the instructions for the main wiki and reading the article, I think it should be https://github.com/Chingu-cohorts/pmrok.wiki.git.

Plus the image is now out of date if we pull from the live wiki instead of the development branch.

[jdmedlock]

You are absolutely correct. I copied and pasted from the Voyage Wiki instructions and then forgot to update the link. It's fixed now. Thanks!!!

[sfiquet]

Just tried to pull upstream with the new command. It's still wrong, there should be a dot before wiki.git, not a dash.

sylvie (development) pmrok-chgmgt $ git pull upstream development
remote: Repository not found.
fatal: repository 'https://github.com/Chingu-cohorts/pmrok-wiki.git/' not found

However I tried with what I thought was the correct url and it doesn't work either because the branch development doesn't exist there:

sylvie (development) pmrok-chgmgt $ git remote add upstream https://github.com/Chingu-cohorts/pmrok.wiki.git
sylvie (development) pmrok-chgmgt $ git pull upstream development
fatal: Couldn't find remote ref development

I know the instructions say to pull into your own branch but that won't exist either? Should I try pulling into master?

[jdmedlock]

I've made a few more changes to correct the Wiki's repo URL and to explain the process more clearly. See if this is any clearer. I'll leave this issue open until you are able to verify.

[sfiquet]

The new process works fine for me.

Just to be nit-picky, I've got three remarks:

One: Updating the development branch?
So, just to clarify, when trying to fix a new issue the process is:

• create and checkout a new branch from development
• pull master from upstream
• do the fix
• push to GitHub
• PR into development

Shouldn't we also pull development from origin (or upstream/master) once in a while? If we never do, it will soon become completely out of date. With that in mind, wouldn't it be better to pull master from upstream into development, then create a working branch?

Two: Include the refresh in the "Making a Change" section
If we want to prevent people forgetting to refresh the repo before working on their fix, I feel that there should be a reminder in the "Making a Change" section. I'd split point 1 into:

1. Create a new working branch with a descriptive name. For example, fix/softskill-url. Any changes or additions to make should be made to this working branch.
2. Refresh the repo with the latest version of upstream/master as described above.
3. Make your changes. Remember to issue frequent commits if you are making multiple changes so there is a detailed trail of each change you've made.

Three: Editing markdown files
Since this is a wiki, the only thing we are editing is markdown files. I can see why you want to keep the ability to edit directly into the wiki for those who have the rights, it's a lot faster and you can test the markdown easily. I wish I could do that too. I hadn't thought of this before but I think it would be fairly simple to do for all contributors: Once we have a refreshed working branch, push it to GitHub, then go on GitHub, select the working branch and use the editor to edit and test the markdown. PR when ready.

To check this I just tried editing a file on an existing branch and I notice that I can edit a file directly in any branch. Then I can commit directly (except for master and development) or I can create a new branch and start a PR. If we could harness this in our process it would make the work a lot easier. Could we maybe have a reference branch that is refreshed regularly from the wiki, and make it protected? Then all that contributors have to do is go on GitHub, select the reference branch, edit any file and create a new branch ready for PR when done. So much faster!

[jdmedlock]

These is an excellent review and suggestions. It's not nit-picky at all and we're evaluating them this morning.

[jdmedlock]

One: Updating the development branch?

So, just to clarify, when trying to fix a new issue the process is:

• create and checkout a new branch from development
• pull master from upstream
• do the fix
• push to GitHub
• PR into development

Shouldn't we also pull development from origin (or upstream/master) once in a while? If we never do, it will soon become completely out of date. With that in mind, wouldn't it be better to pull master from upstream into development, then create a working branch?

Response
This is correct. Since we are dealing with two repos, pmrok-chgmgt and pmrok and since minor changes are sometimes made directly to pmrok pulling from the upstream (pmrok) ensures that you'll always get the current state of the Voyage Wiki.

Since its possible that multiple individuals could have changes underway at any point in time we felt that it was best to only do a one-way push from development to master in pmrok-chgmgt. However, we can reevaluate this as we get more experience with updating the wiki during this Voyage. We could expand the TravisCI script to pull from upstream master back to origin master after a successful change to refresh master on pmrok-chgmgt (aka the origin).

[jdmedlock]

Two: Include the refresh in the "Making a Change" section

If we want to prevent people forgetting to refresh the repo before working on their fix, I feel that there should be a reminder in the "Making a Change" section. I'd split point 1 into:

1. Create a new working branch with a descriptive name. For example, fix/softskill-url. Any changes or additions to make should be made to this working branch.
2. Refresh the repo with the latest version of upstream/master as described above.
3. Make your changes. Remember to issue frequent commits if you are making multiple changes so there is a detailed trail of each change you've made.

Response
This is an excellent point and will be adopted.

Update - Complete. Added to PMRoK wiki

[jdmedlock]

Three: Editing markdown files

Since this is a wiki, the only thing we are editing is markdown files. I can see why you want to keep the ability to edit directly into the wiki for those who have the rights, it's a lot faster and you can test the markdown easily. I wish I could do that too. I hadn't thought of this before but I think it would be fairly simple to do for all contributors: Once we have a refreshed working branch, push it to GitHub, then go on GitHub, select the working branch and use the editor to edit and test the markdown. PR when ready.

To check this I just tried editing a file on an existing branch and I notice that I can edit a file directly in any branch. Then I can commit directly (except for master and development) or I can create a new branch and start a PR. If we could harness this in our process it would make the work a lot easier. Could we maybe have a reference branch that is refreshed regularly from the wiki, and make it protected? Then all that contributors have to do is go on GitHub, select the reference branch, edit any file and create a new branch ready for PR when done. So much faster!

Response

Under Review

I use VScode which has the ability to preview Markdown files. This eliminates the need to push to GitHub to review the appearance of content. However, this should be noted in the instructions and we should point out how this can be accomplished for non-VScode users.

I don't see a problem with what you have proposed in terms of pushing to GitHub and editing your working branch there. I don't know if we need to point this out in the instructions since that can be done in any repo.

See the comments to question #1 above regarding the automatic refresh from the Voyage Wiki to pmrok-chgmgt.