Working with GitHub and PHPStorm

Now that Evo is on a roll again, I have a few patches I had made some time ago that I'd like to offer. With my bad eyes I just don't have the time to fiddle with researching and learning GitHub and PHPStorm on my own, so what I would like to ask is if I can impose on those of you who are using these to help me set them up and get them working, as well as answer questions I have as I go along. Spending a couple of hours on Google or in relevant documentation means I'm done for the day before I've even started actually doing anything.

I already have GitHub and PHPStorm installed, and have a GitHub repository (sottwell/evolution) with a fork from the main modx/evolution repository. I presume this is the proper way to get started. But my first batch of questions is, what are all these branches? Which one should I clone to my localhost to work with? Should I create my own branch here? Can I get rid of some of these other branches in my own repository?

Well, I've learned already that I can just use PHPStorm to clone and manage my local version, no need for the GitHub client. As soon as I figure out (or somebody tells me) which fork I should work with, and how to clone that one, I'll at least have a start.

You should be able to work with just the current development branch (once you find out which one it is) and delete the rest.

$git branch -D branchName (-d will do it unless there are unmerged changes in the branch)

One Git warning. You're probably aware of this, but just in case. Your fork at GitHub is a snapshot and it won't stay up-to-date unless you pull changes from the MODX repo and push them to your fork.

If you issue a pull request, you're asking for them to pull commits from a branch at your fork, which can cause merge conflicts if the fork is not up-to-date and there are changes to the same files you've edited. There's a section in my book that I think is still up-to-date.

Here's roughly what I do to contribute (let's call the fix branch "bugfix" and the MODX dev branch "dev"):

1. Fork the project
2. Clone the project (whether you should clone your fork or the MODX repo is a matter of dispute -- the "official" method is in my book).

When you're ready to work:

3. Switch to the Dev branch, (but never make your own changes there) $ checkout dev
4. pull from the MODX repo to make sure you're up-to-date
5. Create the bugfix branch: $ checkout -b bugfix
6. Make your changes
7. Commit them in your bugfix branch
8. Push the bugfix branch to your fork
9. Issue a pull request asking to pull commits from your bugfix branch into the MODX dev branch

Never merge your changes into the local dev branch. If the pull request is accepted, you'll get them when you pull from the MODX Repo. If it's not, you shouldn't have those changes in your dev branch.

The less time there is between steps 4 and 9, the less likely there will be merge conflicts. You could prevent them with a rebase operation, but I prefer to just work fast and do steps 4-9 late at night (after testing the changes I want to make in another branch that I throw away).

One thing that's hard to get used to with Git after using SVN is that branching is cheap and fast, so you can create a branch almost instantly, mess around in it to test some ideas, then delete it and be confident that your other branches are not affected (unless the ideas work and you want to merge them into your main dev branch).


One other thing to worry about is line endings, I think less so on the mac. You'll know it's a problem if you change a line or two of a file and when you look at the commit on GitHub, and the diff looks like the whole file has been replaced with new content.

PhpStorm is a little unhelpful on this because it will respect the line-endings in the file and, last time I checked, you couldn't force it to use unix line endings when it saves. I have my local Git set to force everything to Unix line endings (both repo and working copy) and PhpStorm seems to leave them alone. There is standard (but disputed) advice about setting the core.autocrlf=true setting, but it didn't really work for me.

Umm... thank you. I think. I'll read this a few more times, and check what you have in the book.

It's not as complicated as it sounds and you can probably do much, if not all, of it in PhpStorm. I'm so used to the command line that I haven't tried using Git in PhpStorm (and I have an odd setup with my extras as separate repos inside the MODX repo).

BTW, GitHub has a GUI Mac Git client: http://mac.github.com/.

I found their Windows client to be unreliable the first time I tried it (possibly due to my odd setup) and haven't used it since.

I did some fiddling around a couple of years ago with the GitHub client, and it seemed to work well enough. I'm finding PHPStorm to be all I need, or at least I think it is. I managed to get the changes I wanted to make pushed to my fork, and submitted a pull request. We'll see if it works as I thought it does.

Cool. The more people who know how to do that, the better.

Now get to work on the Revo bugs.

Can't resist one more tip: Atomic commits. I'm always tempted to do a bunch of work before breaking my concentration by making a commit. When I do that, I'm often sorry later. I try to do one commit per bug/feature and if I can break up the feature into logical steps and commit them separately, so much the better.

Baby steps!

And as far as atomic commits, that's vital, since MODx will only accept atomic pull requests. That was one of the big problems with the falloff in Evo dev; the Russian and Japanese community came up with some really nice stuff, but kept trying to submit major changes all in one big batch. So what was needed was somebody willing to back up and submit one thing at a time.

I have an article started on this business; once I get it all figured out I'll set up a whole series of articles about it.

https://github.com/yama/evolution/commit/1785f2d551abbec805817819354f592dfce80873
Susan, please check this. This is flexible.
thanks.