Travel Mapping

User Discussions => How To? => Topic started by: Jim on October 28, 2017, 08:57:35 am

Title: How users update .list files through GitHub
Post by: Jim on October 28, 2017, 08:57:35 am
I've received an email from a user who'd like to start submitting his list file updates through GitHub rather than pull requests.  Since I have write access, my procedure would be different from the typical user.  Here's how I expect it would work, but I hope some of you who update your lists through GitHub can verify/correct/make better suggestions.

- Create a fork of https://github.com/TravelMapping/UserData, which will be https://github.com/yourgithubname/UserData

- Clone it to your own computer

- Make your changes, commit and push back to your fork

- Create a pull request to get your changes back to the master/origin repository

- Before making future edits, create and merge a pull request in the other direction so your fork is up-to-date with the master

Since most users will be editing a single file, I think it would also be possible to propose edits directly in the master which should create a pull request, but I have not tried that.

Title: Re: How users update .list files through GitHub
Post by: mapcat on October 28, 2017, 09:36:29 am
Since most users will be editing a single file, I think it would also be possible to propose edits directly in the master which should create a pull request, but I have not tried that.
It works. That’s how I’ve always done it. And it removes the need to update everyone else’s .lists in my fork every time.
Title: Re: How users update .list files through GitHub
Post by: michih on October 28, 2017, 09:52:14 am
I agree, directly editing is the easiest way.

Your first user list file submission should be done by sending an email to travmap@teresco.org.
Your user will be added with the next site update and your user list file will be published on GitHub.

To be done once:

1. Sign up on https://github.com and create your own GITHUB user
2. Go to https://github.com/TravelMapping/UserData
3. Press on "Fork"
4. Click on your GitHub user name icon

To be done with every modification of your user list file:

5. Go to your user list file: https://github.com/<yourGITHUBusername>/UserData/blob/master/list_files/<yourTRAVELMAPPINGusername>.list
6. Click on "Edit this file" icon
7. Make your edits or copy the content of your offline user list file
8. Select "Commit directly to the master branch" on the bottom of the page
9. Press "Commit changes"
10. Go to https://github.com/<yourGITHUBusername>/UserData (link on top of the page)
11. Press "New pull request"
12. Check your changes indicated in green and red
13. Press "Create pull request"
14. Press "Create pull request" again

Your pull request will be merged by an admin before the next site update.

To undo your changes, press "Close pull request"
Title: Re: How users update .list files through GitHub
Post by: michih on October 28, 2017, 09:53:47 am
Is it necessary to be added to the TM team (https://github.com/orgs/TravelMapping/people) or can everyone edit his user list file?
Title: Re: How users update .list files through GitHub
Post by: Jim on October 28, 2017, 10:13:37 am
Is it necessary to be added to the TM team (https://github.com/orgs/TravelMapping/people) or can everyone edit his user list file?

Anyone should be able to edit through the fork/pull model.  Twice as many users have commits in the UserData repository as we have people listed as part of the team.

Thanks for the more detailed instructions.
Title: Re: How users update .list files through GitHub
Post by: mvak36 on November 04, 2017, 11:56:33 pm
I followed the instructions and it worked great. Thank You Jim and michih for putting those on the forum.

We only have to fork the repository once right? If I want to update my file later on, I don't have to fork the main Travel Mapping repository again do I?

I know that michih said that we only have to do it once. This is just more a question for me to learn how Github works. Since I will only be updating my file, I should be ok with not having to Fork the repository again right?
Title: Re: How users update .list files through GitHub
Post by: yakra on November 05, 2017, 01:00:27 am
You will not need to fork the repo again.

To update your own fork to sync with the TM master, you would put in a pull request to sync that branch back into yours, but since you'll only be updating your file, you won't even need to do that.
Title: Re: How users update .list files through GitHub
Post by: mvak36 on November 05, 2017, 10:55:07 am

To update your own fork to sync with the TM master, you would put in a pull request to sync that branch back into yours, but since you'll only be updating your file, you won't even need to do that.

How would I do this? I'm just curious in case I want to do it in the future.

Thanks in advance.
Title: Re: How users update .list files through GitHub
Post by: oscar on November 05, 2017, 11:27:26 am

To update your own fork to sync with the TM master, you would put in a pull request to sync that branch back into yours, but since you'll only be updating your file, you won't even need to do that.

How would I do this? I'm just curious in case I want to do it in the future.

Thanks in advance.

Depends on what kind of GitHub client you're using. In the Github Desktop client for Windows which I use, there's a "sync" button near the upper right corner that simplifies the process.

It would be a good idea to do a sync just before you make changes to your list file, to make sure your fork has the latest version of your file before your changes.
Title: Re: How users update .list files through GitHub
Post by: yakra on November 05, 2017, 01:50:29 pm
How would I do this? I'm just curious in case I want to do it in the future.

Thanks in advance.
Depends on what kind of GitHub client you're using. In the Github Desktop client for Windows which I use, there's a "sync" button near the upper right corner that simplifies the process.

If using the GitHub web interface, rickmastfan67 described the process on AARoads (https://www.aaroads.com/forum/index.php?topic=16341.msg2090192#msg2090192):
Quote
Web interface:
1. https://github.com/TravelMapping/HighwayData
2. Look for the little 'green' icon beside the 'Branch: master' pull down and click it.
3. Look for the "compare across forks" text link and click it.
4. Change the 'Base Fork' to yours.
5. Hit the 'Create pull request' button.

Then you should be able to update your copy of the 'Master' on your fork. ;)

It would be a good idea to do a sync just before you make changes to your list file, to make sure your fork has the latest version of your file before your changes.
If mvak36 is editing the file in his own fork, then it will by definition have the latest version, and this should not be necessary.
Title: Re: How users update .list files through GitHub
Post by: mvak36 on November 05, 2017, 03:52:45 pm
How would I do this? I'm just curious in case I want to do it in the future.

Thanks in advance.
Depends on what kind of GitHub client you're using. In the Github Desktop client for Windows which I use, there's a "sync" button near the upper right corner that simplifies the process.

If using the GitHub web interface, rickmastfan67 described the process on AARoads (https://www.aaroads.com/forum/index.php?topic=16341.msg2090192#msg2090192):
Quote
Web interface:
1. https://github.com/TravelMapping/HighwayData
2. Look for the little 'green' icon beside the 'Branch: master' pull down and click it.
3. Look for the "compare across forks" text link and click it.
4. Change the 'Base Fork' to yours.
5. Hit the 'Create pull request' button.

Then you should be able to update your copy of the 'Master' on your fork. ;)

It would be a good idea to do a sync just before you make changes to your list file, to make sure your fork has the latest version of your file before your changes.
If mvak36 is editing the file in his own fork, then it will by definition have the latest version, and this should not be necessary.

Thank You both for your replies. I don't think I would need to sync with the master version again, but I just want to learn how to do it. That guide you posted helps. :) Edit: I don't see a green button other than the "Clone or Download" button. Is that what the guide was referring to?
Title: Re: How users update .list files through GitHub
Post by: mapcat on November 05, 2017, 06:15:55 pm
I don't see a green button other than the "Clone or Download" button. Is that what the guide was referring to?
The interface changed slightly since that was posted, and now it's grey: "New Pull Request".
Title: Re: How users update .list files through GitHub
Post by: mvak36 on November 05, 2017, 09:27:37 pm
I figured that's what it was. I was playing around with Github after I posted the question. It's good to know for future reference. Thanks everyone.

EDIT: I did a trial run where I synced my fork to the Master branch. It looks like it worked.
Title: Re: How users update .list files through GitHub
Post by: Craziaskowboi on February 17, 2018, 09:08:34 am
I created a GitHub account, forked to TravelMapping, and moved and dropped my .list file into the window. Will that work? I'm totally lost with this stuff.
Title: Re: How users update .list files through GitHub
Post by: mapcat on February 17, 2018, 09:23:29 am
Which repository did you put it in? You still need to submit a pull request to get it added, and since there aren't any open pull requests in UserData at the moment, it looks like you haven't done that yet.
Title: Re: How users update .list files through GitHub
Post by: michih on February 17, 2018, 10:07:41 am
I created a GitHub account, forked to TravelMapping, and moved and dropped my .list file into the window. Will that work? I'm totally lost with this stuff.

Your first user list file submission should be done by sending an email to travmap@teresco.org.
Your user will be added with the next site update and your user list file will be published on GitHub.

Well, you directly tried to add your file. Should be fine.

1. Sign up on https://github.com and create your own GITHUB user
2. Go to https://github.com/TravelMapping/UserData
3. Press on "Fork"
4. Click on your GitHub user name icon

Done!

https://github.com/Craziaskowboi/UserData/tree/master/list_files

Now, click on "Upload files", drop your file into the window and:

8. Select "Commit directly to the master branch" on the bottom of the page
9. Press "Commit changes"
10. Go to https://github.com/<yourGITHUBusername>/UserData (link on top of the page)
11. Press "New pull request"
12. Check your changes indicated in green and red
13. Press "Create pull request"
14. Press "Create pull request" again

Your pull request will be merged by an admin before the next site update.

To undo your changes, press "Close pull request"
Title: Re: How users update .list files through GitHub
Post by: Craziaskowboi on February 17, 2018, 01:35:01 pm
OK, so how do I visualize all the stuff I entered on a map?
Title: Re: How users update .list files through GitHub
Post by: mapcat on February 17, 2018, 03:13:45 pm
OK, so how do I visualize all the stuff I entered on a map?
You’ll see it after the next update assuming there were no problems with the pull request.  The updates usually run daily in the evening.
Title: Re: How users update .list files through GitHub
Post by: Jim on February 17, 2018, 04:09:14 pm
OK, so how do I visualize all the stuff I entered on a map?
You’ll see it after the next update assuming there were no problems with the pull request.  The updates usually run daily in the evening.

I don't see a pull request yet.  If GitHub gives you trouble, you're welcome to email me the file and I'll put it in.  I'd estimate about 2/3 of our users steer entirely clear of GitHub.

In any case, expect a site update between 9 and 11 PM Eastern most nights.