search

ebeshero / Amadis-in-Translation

a project to apply TEI markup to investigate early modern Spanish editions of Amadis de Gaula and their translations into English and French from the 1500s to the early nineteenth century.
http://amadis.newtfire.org
GNU Affero General Public License v3.0
4 stars 6 forks source link

GitHub Hygiene: Forking this Repository #47

Open ebeshero opened 8 years ago

ebeshero commented 8 years ago

@setriplette @HelenaSabel @sydb Now hear this! We are herewith implementing a standard practice in which collaborators shall fork this repository, so each of you will work on her/his own fork and issue a "pull request" when you wish to place something in the the central (origin) repository. (To @setriplette this is new, but Helena and Syd know how to do this.) We're doing this because it's more standard practice and will help protect us from pushing local problems (like accidentally deleting a directory) into the origin and overwriting everyone else's local repositories when they sync. Stacey, I'll walk you through it when we get together and have a little time--it's not hard. Basically what it means is you issue a commit and send it as a "pull request" which means that you request me (as the owner of the repository) to pull your commit into the origin if it looks okay.

We also don't need to do this immediately, so if you have changes and you're not comfortable with forking yet, just push them through as usual until we have a chance to go over how to do this together.

ebeshero commented 8 years ago

Also--no worries--this is a practice I'm about to implement in all the repositories I've launched that I share with others, and it's not motivated by any particular issues we've had here! (We've had a pretty good experience here, actually--but still, we'll be safer I think if we get used to the forking method.)

HelenaSabel commented 8 years ago

Done! May I make a suggestion? there are some folders in the master branch named "log" that worked as my and since now we'll all have our working stations, it makes more sense to only have the more stable versions in that branch. The same should be done with the ODD trials, right?

ebeshero commented 8 years ago

Sure--and I notice some old code I helped work on back in Sept. with you in that log folder, so I think I'll just move it into my "Elisa" branch (so it'll be there if the group needs it)... and try cleaning up some of the ODD stuff that way, too. So I think the Elisa branch will contain a sort of "attic" library of old or experimental code we might want to consult. @HelenaSabel

ebeshero commented 8 years ago

@sydb @HelenaSabel @djbpitt At issue: How does one maintain the distinctiveness of a GitHub branch (to contain additional files not ready for the origin), but keep the branch up to date with the latest changes to project files in the origin? I ask in this context: Helena and I decided it would be best to remove the ODD files out of our origin/master branch to work on them on my "Elisa" branch until they're ready to actually be applied to the project. So I have "moved" all the ODD work over to my "Elisa" branch of this repository, and removed all the ODD related files from the "master"/ origin just until we get the ODD work stable so it can accommodate and output our Schematron rules. If you're looking for the ODD files in Amadis-in-Translation, go and checkout the Elisa branch and let's work on that over there.

One thing I'm not quite sure how to deal with is how best to keep that branch in sync with project changes we'll certainly be pushing to the origin in the future. I did a clunky sort of workaround just now when I wanted to put Helena's changes in my branch and preserve the files I wanted to keep there but not in the origin:

ebeshero commented 8 years ago

Here's a lead, I think: https://github.com/WCSim/WCSim/wiki/How-to-Keep-your-Branches-Up-to-Date

RJP43 commented 8 years ago

I'm not trying to intrude but this is the fork and branch method that I am leading students through on the new GitHub tutorial. By my understanding, this will allow you to keep the origin forked repo. synced and the individual's development is done in a cloned branch of the forked repo. A general diagram to explain what I mean is below:

forkandbranchmethod

And here is the page this diagram is from where you can find more information.

@ebeshero I'm not sure if this is of any help and if not feel free to delete, but when I saw you were discussing this here I figured I would share.

ebeshero commented 8 years ago

@RJP43 Hi Becca-- yes, these diagrams are really helpful! Thank you. The problem here is that I can't fork my own repository--so I created a branch of it where I'm storing some things that I don't want to keep in the origin. It may be that my branch will behave a lot like a fork, but what we're really after here is to keep the branch or fork up to date with the origin without losing the local stuff we're working on in the merge or pull. I think the word "upstream" is the operative one here--that we pull changes from upstream and somehow guard our distinctive material in the branch or fork.

And we should probably experiment with both of these to make sure we're confident how to use them. One thing that worries me a little about the Amadis case is that I'm storing an older set of files here that I removed from the origin/master one or two commits ago. Until we edit all the ODD and experimental schema files in my Elisa branch, they might look like old material to GitHub and I am hypothesizing that they'll quite likely be overwritten in a merge! And there's one way to find out--experiment. I'm just leaving some notes here to defer this until I've got my syllabi posted and have time to play with this again. Thanks for posting your diagram, too!

setriplette commented 8 years ago

Elisa,

I’m counting on you showing me this sometime this week. I sort of understand, but I still have questions.

S

— Stacey Triplette Assistant Professor of Spanish and French Humanities Division University of Pittsburgh at Greensburg Faculty Office Building 200 150 Finoli Drive Greensburg, PA 15601

On Jan 4, 2016, at 8:16 PM, Elisa Beshero-Bondar notifications@github.com<mailto:notifications@github.com> wrote:

@RJP43https://github.com/RJP43 Hi Becca-- yes, these diagrams are really helpful! Thank you. The problem here is that I can't fork my own repository--so I created a branch of it where I'm storing some things that I don't want to keep in the origin. It may be that my branch will behave a lot like a fork, but what we're really after here is to keep the branch or fork up to date with the origin without losing the local stuff we're working on in the merge or pull. I think the word "upstream" is the operative one here--that we pull changes from upstream and somehow guard our distinctive material in the branch or fork. So this seems pertinent: https://help.github.com/articles/syncing-a-fork/

— Reply to this email directly or view it on GitHubhttps://github.com/ebeshero/Amadis-in-Translation/issues/47#issuecomment-168861945.

ebeshero commented 8 years ago

@HelenaSabel @RJP43 @djbpitt Becca and I and a couple of other students here at Greensburg discovered something really important this evening. You may have figured it out already:

Becca and I are working on writing up a How-To guide summing up all this. The weirdness we experienced with forking has everything to do with the source from which we cloned our original repos. We couldn't clone a fork over an existing repository of the same name, or when we did manage it, we had problems with identifying the fork vs the remote origin, and we needed to recreate our Git config file after destroying the local repo to solve that. The situation we're experiencing is distinct to our ongoing projects like Nell Nelson and Amadis, since we're changing our workflow, and is unlikely to be an issue for new projects our students set up, so long as our students know they need to clone their forks and not the remote (upstream) origin.

djbpitt commented 8 years ago

Dear All,

I'm not confident that I've understood the issues correctly, but with that said:

If you have cloned (not forked) the original repo and then created a new local branch, you need to push that to the origin to make it part of the original repo. When you push, you push only the branch you've checked out (that is, the one you're working in; if you have only a master branch, that's checked out by default). That means that when you create a new branch, you have to push from it if you want it to be included in the origin on GitHub (and typically you do).

If you have forked a repo, your fork does not maintain a live connection to the original repo, either on GitHub or in any local clone. That has a couple of consequences:

  1. If you originally cloned the regular repo and then want to create a fork, cloning the fork over your local clone of the original doesn't really make sense because the two are different repos as far as GitHub is concerned. If you want to maintain local clones of both the original and your own fork, you can do that by creating them in different places in your disk hierarchy. If you want to delete your local clone of the original repo and replace it with your clone of your fork, deleting the local repo makes sense, since you're really replacing your clone of one repo with your new clone of a different repo.
  2. Your third step is important: What happens if you fork a repo, and do your own work in it in one or more branches, while the original source from which you forked continues to be updated? If you want to incorporate the updates that have happened in the original source since the time you created the fork, you have to merge them in, as Elise writes, since the fork does not maintain a live connection to the original source after it has been created.

Gotta teach now ...

Best,

David

On Fri, Jan 8, 2016 at 12:57 AM, Elisa Beshero-Bondar < notifications@github.com> wrote:

@HelenaSabel https://github.com/HelenaSabel @RJP43 https://github.com/RJP43 @djbpitt https://github.com/djbpitt Becca and I and a couple of other students here at Greensburg discovered something really important this evening. You may have figured it out already:

  • If you have been a collaborator on a repository with full push access to the remote origin, where nobody was working in a fork, and you originally started work in that repo by cloning it locally, this makes for a problem (at least it did for us) when you make a branch.
  • The problem is that your local Git config file is still set to track the remote origin as the default push location. You need to fully delete your local repo, and clone again from the fork.
  • And to keep your fork updated, you need to identify the remote origin (ebeshero/Amadis-in-Translation) as the upstream origin, from which you fetch updates into a branch and merge with your fork (like taking a pull request in reverse!)

Becca and I are working on writing up a How-To guide summing up all this. The weirdness we experienced with forking has everything to do with the source from which we cloned our original repos. We couldn't clone a fork over an existing repository of the same name, or when we did manage it, we had problems with identifying the fork vs the remote origin, and we needed to recreate our Git config file after destroying the local repo to solve that. The situation we're experiencing is distinct to our ongoing projects like Nell Nelson and Amadis, since we're changing our workflow, and is unlikely to be an issue for new projects our students set up, so long as our students know they need to clone their forks and not the remote (upstream) origin.

— Reply to this email directly or view it on GitHub https://github.com/ebeshero/Amadis-in-Translation/issues/47#issuecomment-169904234 .

ebeshero commented 8 years ago

I'm just copying Becca's command line notes here for ease of reference. These may need some fine-tuning (as in, some of this, like designating an "upstream" branch may not be absolutely necessary since you can always choose an https URL to enter, but could be convenient so you only ever have to type the word "upstream" to know where you're headed). We used these notes as ready reference while I was orienting @setriplette to forking and pull requests this afternoon.

Working Command Line From a Local Fork:

Created a fork - working on local computer in local fork if origin is the fork -- origin set to local fork name in order to be synced to original repo. need to tell GitHub what is upstream from the local forked repo. Commands:

  1. git remote add upstream (then put https link of original repository : identifying what upstream is
  2. git remote -v : this quickly verifies that origin is forked repo. and the upstream is original repo.
  3. git fetch origin -v : fetching any changes made in origin repo.(local fork)
  4. git fetch upstream -v : fetching any changes made in upstream repo. (original)
    this stored upstream changes in an "upstream branch" on the fork
  5. git merge upstream/master : merges fork with branch made from the fetched upstream changes
  6. git push : pushed changes to local origin (forked repository)

from there created pull request to original repo.

Further Notes and Things to Test (ebb)

ebeshero commented 8 years ago

@HelenaSabel @setriplette Just a quick note: Stacey and I didn't actually push any changes of any kind to the repositories today, but I just concentrated on orienting Stacey to forking and a bit of the command line terminal environment on her Mac. And we concentrated on big project questions, as you see in https://github.com/ebeshero/Amadis-in-Translation/issues/50 We'll return to do a test of pushing and pulling and fetching and merging tomorrow midday.