Add handbook page for cvs to git migration with Eclipse

This needs a bit of polishing and editing, but it has some good information that we need to get into the Handbook. Audience is current Eclipse/CVS users who contribute to Drupal core or contrib project, and need to migrate to git.

Not sure yet where it belongs.

The target could be at git handbook page for egit ;-).

good idea, thanks!

Yeah, that's a good question. A lot of our CVS-specific docs have information that won't be changed in it (like how to set up a project). We'll have to comb through and figure out what documentation we need to keep.

Is there a tag for git migration that we should be adding to this issue? There's a LOT of doc that needs to be fixed up, extracted, or archived...

tagging

tagging again

Based on conversation in irc with jhodgdon:

Anything related to git that can be completed before deployment should be tagged "git phase 2"

Anything that will need changing as soon as possible after deployment should be tagged "git deployment"

All should be tagged as "developer"

For items tagged "git deployment" the plan is:
(a) create temporary child page with CVS information replaced with git.
(b) at migration time, move the child page up in the hierarchy, and move the original parent page into the Archive book (where it will get unpublished sooner or later).

I'm not sure if we need a plain git tag or not.

I don't really see managing specific tools like this (Eclipse) as being part of the git migration. I'd like to untag this from the migration. I'm all in favor of offbeat things like this being handled, but I don't think it's critical path.

Note: I am also an Eclipse user. However, egit does not work very well in the context of nested projects, as most people do with Eclipse.

Having tried and failed to add a Drupal project as an Eclipse project today (until aspilicious walked me through it in IRC), I think that having a page in the Git docs for how to do this would be helpful.

I'm not sure the Google doc referenced here is the right doc... I was able to follow http://wiki.eclipse.org/EGit/User_Guide#Starting_from_existing_Git_Repos... OK (and I don't think we need to reproduce it on d.o), but there was one glitch that aspilicious helped me with. If you use the New Project wizard to set up the project, the pull/import does not work. You need to select "General project" for it to work.

Anyway. I might see about adding a page about using Eclipse to the git docs, if someone else doesn't get to it first.

One note: after setting a project up as a "general" project, you can (outside of eclipse) edit the .project file to make it into a PHP project (assuming you have the PDT installed). I'll work up some instructions, even though it is a hack - if you want to debug and have the other PHP project features, I think you need the project to be a PHP project.

And furthermore I will also say that I didn't have any success in first creating a PHP project and then using the Share Project command in Eclipse to attach it to git.

Oh, I figured out how to do this. Here is a brief outline of what I think should go into the page on d.o git with Eclipse. As usual, we don't really want to duplicate official Eclipse documentation -- just point out where it is and how it relates to Drupal.

a) After installing Eclipse, install the PDT (PHP Development Tools) package and the EGit (Eclipse Git) package. There are guides on how to install them on their respective project pages: http://www.eclipse.org/pdt/ and http://www.eclipse.org/egit/.

b) Make a directory/folder on your computer to hold your Git repositories.

c) In Eclipse, find the Git settings (under Window / Preferences / Team / Git -- may be Edit / Preferences or Edit / Preferences on some platforms). Tell Eclipse where your Git repository is on the main Git screen. You can also set up your user name and email address on the Git / Configuration screen, by doing "New Entry". See http://drupal.org/node/1022156 (Identifying yourself to Git) for more information on which config entries you need to set up.

d) Also in the preferences under General / Workspace, set your default text file encoding to UTF-8, and the default line endings to Unix.

e) To import a Drupal project using Git into your Eclipse workspace, follow the general EGit instructions: http://wiki.eclipse.org/EGit/User_Guide#Starting_from_existing_Git_Repos...
- The repository location to use when you click "Clone" in the first step is: http://git.drupal.org/project/[name].git, where [name] is the name of the project. For instance, to import the Drupal project, the URL is http://git.drupal.org/project/drupal.git, and to import the Admin Menu project, the URL is http://git.drupal.org/project/admin_menu.git. If you are importing the Drupal project, you may want to choose only a subset of the branches, rather than all of them, to save time (assuming you don't need access to for instance Drupal 4.7).
- Once you have cloned the repository that you need and selected it, choose "Use the New Project Wizard" when you get to the screen that asks what wizard to use.
- On the next screen, choose "PHP Project".
- On the next screen, choose Create Project from Existing Source, and find the Git repository you just cloned (see attached screen shot).
- Click Finish, and your workspace should be set up.

f) I think we might want to include other sections on this page on how to do the common operations that are explained in http://drupal.org/node/1054616 (patch contrib workflow) and other Git doc pages? As I haven't gotten that far yet, I am not sure what to put on them... Thoughts?

RE #14 - Some other useful config items for (c) -
- General / Content Types - add .module, .install, and .test to the file extensions recognized to be text/PHP, and .info to the file extensions recognized to be plain text.

I was wondering where this should go, and after some digging, I found: http://drupal.org/node/777182 (GUI tools in the Git docs section). I think maybe this section needs to be placed at the upper level of the Git handbook so it can be found? But meanwhile, I added a child page and put the information above in there. It's a start at least...

http://drupal.org/node/1077484

Needs a review, and needs information on how to import a project for read/write access, make patches, and other Drupal/Git workflow tasks.

Thanks for those outlines! I will test them as I have time (and the need for the processes), and add them to the page. Probably a table of contents at the top of the page would be helpful too, once there are multiple sections in the page.

Well, I don't know about that... let's at least get the information out there and then we can get it in the right place. Or if you figure out where it should go before I put the info out, then I'll put it in the right place...

Anyway, I needed to make a patch for a contrib module today, so I just added a section about how to make a patch, based on #18 (which worked for me).

http://drupal.org/node/1077484#patching

Also added a table of contents at the top of the page...

After some Git tutorials at DrupalCon, I now think the patching section I added recently should be revised to start with making a branch, as in the non-Eclipse git workflow that it is supposed to mirror.

I'm not sure how http://drupal.org/node/75242 related to the Eclipse updates, but it's one of the last links tagged in the 'git deployment' sets for update. Perhaps while you all are working on this you could take a look at what to do with it?

My thought on what to do with these pages:
a) 1077484 (the page we've been working on here) should link to 75242 (general Eclipse dev tool page referenced in #23). And vice versa.
b) The CVS section of 75242 should be completely removed.
c) The section at the top of 1077484 that covers Eclipse setup should be moved to 75242 instead and replaced with a link to 1077484.
d) Anything referencing patch making or other workflows in Eclipse that is in 75242 should be removed and replaced with a link to 1077484.

#22 still needs to be addressed too.

My mission today is getting the old CVS references out, so I completed b) and d)
As far as patching was concerned, there was just a general reference to be sure Eclipse was configured to roll and apply patches. It seemed clearer to remove that until #22 is done.

@jhodgdon: great work on http://drupal.org/node/1077484! just what I needed, right when I needed it. Kudos!

Back in #9, before this was expanded to a separate page, aspilicious talked about putting info into Configuring Eclipse (#75242).

I'd like to put a note in there now where the CVS info was. How about something simple like:

EGit is a plug-in that provides some basic git capabilities in Eclipse. Eclipse/EGit (Windows, Linux, Mac) describes how to use EGit with the drupal.org repositories.

If someone new comes to the Configuring Eclipse page, I don't want to leave them without any information on d.o. + version control + Eclipse.
I'm just jumping into this (git documentation), and have tried to read thru the issue queue to understand the priorities, etc. So I'm not totally clear on whether we should wait to change or not. (I do get that it's not on the critical path right now.)

Cross linking added as per comments #26 and #24.

Remaining items to be done on http://drupal.org/node/1077484 as far as I can tell:

1) Comment #22 - revise the patching discussion to suggest making a branch before committing the code. Also add section from http://drupal.org/node/707484 on how to clear the patch after you're done.

2) Add section on applying patches, based http://drupal.org/node/1054616 adapted to Eclipse

3) Add section on feature branches from http://drupal.org/node/1054616 adapted to Eclipse

4) Add section for project maintainers from http://drupal.org/node/1059322 adapted to Eclipse

5) Anything else we haven't added yet from comment #18 above.

Note: I think that the "advanced" workflows that aspilicious added recently to http://drupal.org/node/1077484 at the bottom may cover some of these topics... I would prefer that we not put outlines in this note format on 1077484 until they are fleshed out a bit more, because off-hand I wasn't sure what those were for. Probably they should be moved back to this issue until they make more sense.

Here's the unfinished section, which has been removed from the page until it can be made into something a little more comprehensible:

// Aspilicious fullcalendar fork workflow
// Needs a wrokflow and a style review

<h3 id="workflows">Workflows (advanced)</h3>
<p>If you contribute a lot to one specific module but you don't have write access you will be interested in the following workflow</p>
<ol>
<li>Clone the project</li>
<li>Create a local branch where you work on your new feature or bug fix</li>
<li>Create a new sandbox, call it for example "module_name [my_name fork]</li>
<li>Add the sandbox as a new remote to your project (see add additional remote)</li>
<li>Make some changes and commit those to your new branch</li>
<li>Push those changes to the sandbox. (see push to new remote).</li>
<li>Give the sandbox link + branch name to the maintainer so he can merge your bug fix or feature into the main branch.</li>
</ol>

<h3 id="remotes">Add additional remote (advanced)</h3>
<ol>
<li>Go to the repository view (right click on project, Team > Show in repository view</li>
<li>Create the remote (right click on remote, Create remote)</li>
<li>Choose a new and select all the options</li>
<li>Change fetch url (see part about connecting to git repository with write access)</li>
<li>Click "Select all branches spec"</li>
<li>You don't need to add new push uri's</li>
<li>Click again on "Select all branches spec"</li>
<li>Finish</li>
</ol>

<h3 id="remotes">Push to new remote (advanced)</h3>
<ol>
<li>Create a new remote (if the desired remote isn't created yet)</li>
<li>Right click on your project, and in the pop-up menu, choose Team > Remote > push.</li>
<li>Select the remote you like to push to</li>
<li>Click finish (or a couple of times next if you would like to verify or change some settings)</li>
</ol>

<strong>NOTE:</strong>
If it asked to configure the pull strategy you should leave the defaults.

RE comment #18 and #27 above - here's the only thing I think we need to add from #18:

******
What if you would like to edit your patch?

- Reset (mixed) to the branch you like to patch. Mixed leaves the changes you made intact. Kind of a revert patch.
- Make some changes
- Commit again
- Create new patch
******

So, the remaining to do items are:

1) Comment #22 - revise the patching discussion to suggest making a branch before committing the code as in http://drupal.org/node/1054616 (or add this as an alternative way to make a patch)

2) Add section from http://drupal.org/node/707484 on how to clear the patch after you're done.

3) Add section on applying patches, based http://drupal.org/node/1054616 adapted to Eclipse

4) Add section for project maintainers from http://drupal.org/node/1059322 adapted to Eclipse

5) Item above in this comment about what to do if you need to modify an existing patch (see if there is a workflow on 707484 or 1054616 about this?)

6) What are the workflows in comment #29 for, and are they covered by these to dos or not? If not, they should be added too.

I just added stub sections to http://drupal.org/node/1077484 for all of the things I think are missing, and am working on them today. I'll try to remember to un-assign this when I run out of steam, but if you come by in a few days and want to work on this, you can probably assume I'm not working on it actively and assign this to yourself instead (whoever you are). :)

I've added a few things... remaining To Dos are marked "TODO" in http://drupal.org/node/1077484

Some questions I have:
a) Rebase - can this be done in EGit, and if so, how? I'm looking at http://drupal.org/node/1054616 and not sure how to do the rebase. Maybe the "Fetch from upstream" dialogs handle this, but I am not sure?

I guess that's it for now... I'm still editing...

aspilicious answered the rebasing question on IRC, so that has been updated. There are still some TODO items in http://drupal.org/node/1077484 in the patch workflows section, but not too many. Getting closer!

I think I'm done editing that page for this session... if someone else wants to write the few remaining patch sections and/or review what's there, that would be lovely.

I am in agreement with aspilicious: You want to make sure that you have the most current snapshot of what is in the d.o. repo before you apply and roll your patch. You should use fetch for that, commit your patch, then rebase. One of the main effects of rebase is that it will 'flatten' the merge history. You should do that before you commit your patch, but you may not want to reabase until then because you may want to keep your local history of changes 'unflattened' in case you run into trouble.
See step #3 under Creating patches via feature branch on the More Advanced Patch Contributor Guide.

You have the steps correct, but then the paragraph on Rebasing doesn't quite make sense.

Sometimes between the time when you start working on a patch and when you are ready to submit your patch to review, the main branch you based your patch on has been updated, because someone committed changes to it. If this happens, you need to "rebase" before creating your patch.
I would remove the "If this happens...." sentence because (a) you always want to do a fresh fetch so that you have the most current version of the code and are sure to incorporate any changes that have been commited on d.o, and (b) the command you need to use is "fetch" (or perhaps "pull"), not rebase.
Rebasing means that you will basically apply the changes from the main branch into your local branch, so you will now be basing your patch off the current state of the main branch, instead of off what it was when you started work.
Well, um, not exactly. I really think you want to talk about "fetching," not "rebasing."

So how about this:

Sometimes between the time when you start working on a patch and when you are ready to submit your patch to review, the main branch you based your patch on has been updated because someone committed changes to it. To make sure you have the most current version of the code from the repository, you need to fetch from the repository. This will get the most recent code and put it into your local repository. You can now add your changes to this updated branch so that your code will be applied to the most recent version.

OK -- those last sentences are a bit repetitively redundant. Perhaps someone can tighten them up.

I believe I've addressed #35, 36, 37 -- if you could review those sections, that would be helpful.

There are also still several TODO sections to be filled in.

Is this still relevant? I can't imagine anyone migrating from cvs to git (in Eclipse) now.

I'm closing the issue as outdated. If there is still something that should be added to out Git documentation, it's maybe better to create a new issue?