The documentation for dealing with official WP repository is exclusively about using command line. While I have no bias against that, I do have little experience with VCS and two (or three) different ones I will have to figure out and use in nearest future.
So for now I wing it with VCS integration features in IDEs (NetBeans, PHPStorm). Which often leaves me confused on specifics and ways of doing things properly.
Are there any good articles/posts/guides on using official SVN repository (or at least SVN in general) with IDEs or other GUI-based tools? Something that focuses on concepts and workflow, rather than typing in arcane lines in console.
Below are the methods you can try. The first solution is probably the best. Try others if the first one doesn’t work. Senior developers aren’t just copying/pasting – they read the methods carefully & apply them wisely to each case.
Im going to make this answer a blog article since it went slightly off-topic GRIN.
On http://wp.leau.co/2011/02/25/how-to-setup-your-wordpress-php-development-environment/ in chapter 6 I made some explanation for SVN in eclipse but you are probably looking for something else.
The story I made here was about your comment
“So for now I wing it with VCS integration features in IDEs (NetBeans, PHPStorm). Which often leaves me confused on specifics and ways of doing things properly.” and “Something that focuses on concepts and workflow, rather than typing in arcane lines in console.”
I have heard that one more often I wanted to explain SVN in a broader context e.g. describing “programming languages” first and then explain PHP makes you understand PHP better and in this case Configuration Management first and then the SVN solution in it.
I will just type something here and if it is off-topic or not needed then I will delete it:
If you install Eclipse PDP, I have written this: [ http://wp.leau.co/2011/02/25/how-to-setup-your-wordpress-php-development-environment/ ]
If you scroll down to #6 I explain briefly how to install collabnet subclipse in Eclipse (basically just point to the server select all and install)
In Eclipse with whatever version management tool, the commands for version management are always under rightmouse click “TEAM”. Since you can switch between projects you can have support for multiple version management tools and most commands are familiar over tools via the GUI.
As YOU know: For a new WordPress plugin project you get a svn location from WordPress.org (in your mail box), they use the Trunk for your latest code and “tags” copies for stable releases. (VERY basic CM pattern). This is what you see at first glance.
So your project will be linked to TRUNK. and you can simply commit to that. This is the place you work in (but not where you release from) (unless you specify ‘trunk’ in the readme.txt as location for your final code).
Furthermore you can include the WordPress /wp-includes and /wp-admin in your Eclipse project as libraries so that you can lookup functions and see deprecated functions. These are not writeable and so fall not under version management (!). This is from client side so not the “externals” which actually link in the version management project.
As soon as you have a stable version, select the stuff and rightclick “team” and “create tag/branch”, this opens up the WordPress svn location and you can select the tags directory and type a new number and your new version is live (which is maybe of use for someone reading this). Notice that you should not select the root of your project but everything else or else it will create that root also under your tags/2.3.4 which is not what you want you want everything under the root to be in your /tag directory.
See the posting for some screen shots.
WordPress itself Contributor
If you are a contributor you can use the same as above but you create “patches” from changes you made. “Patches” is a concept in the CM world e.g. subversion provides this or jazz RTC. With right mouse click “Apply patch” you can apply a patch if you have a patch that has not yet been applied to the WordPress trunk.
Some people also commit directly to the trunk.
WordPress itself “Read”
Just create a project ‘WordPress’ which contains a checkout of the /LATEST version in the trunk (of the subversion code), again, via team > checkout.
Personally I don’t do this but just use an export of the latest code (with force) to just get a directory with the latest WordPress version (so which does not fall under any version management)
Since you have some experience with VCS and with questions around SVN: Basically all version tooling is about the concept of naming things. Or better said having the best namespace. You can map most commands from CVS, Git, RTC, ClearCase, SourceSafe etc… to the concept around this namespace. Since you have some/little experience with other tools, a little broader:
New people often stare themselves blind on certain commands or a specific piece of functionality but providing the best option to place all elements needed in a namespace is the core thing.
So since this is basically the core functionality of these tools the term “version management” is wrong. It is actually a name-space-manager.
So if you have
/project A/department B/Team C/Member D/Stream E/Component F/Element G/Branch H/ Branch I/Version J
You can create a unique name for each “thing”. The above is a implementation of a namespace
you need for a certain purpose using one of the namespace tools.
Almost all concepts in this world can be mapped to this so the the way you CAN support your custom namespace/taxonomy depends on the capabilities of your tool. So … it depends really on the concepts and choices the designers of the hundreds of different tools have made.
In a good tool you can click and see this complete taxonomy in one tree or zoom in one that one tree.
That is the core: a tool that can help you manage complexity (see complexity in wikipedia: http://en.wikipedia.org/wiki/Complexity ) by giving you good tools to manage YOUR CUSTOM taxonomy. The person creating the taxonomy an thinking how to set it up is the configuration manager he write a plan called the configuration management plan thinking this out first.
Just imagine someone asking you to create a set of custom taxonomies in WordPress that represent ALL objects in his company including the ability to get the state out of it as it was at any given moment. You can make a lot of design choices and everyone will produce something else based on some choices. Some will contain more features some are more simple and the more complex ones all made different decisions. This is “these tools”. So I never understand discussions on tool level about version management because that is completely weird.
In PHP nowadays you can make namespaces you make a hierarchy with directories, apply naming conventions to objects and within them methods. If you take one file which you have placed in a hierarchy, take it a step further. You add one / behind it and place a version number behind it. That is even not enough because you would want team A working on version 4 of the file and team B working on that version. So you add another / and add the branch id. This is how you build the namespace. Depending on the tool you can go as crazy as you would like.
But it means: if someone comes to you asking “where is document Z” you can not give the answer. Because in a version management system “document Z” does not exist. And even when he says give me “document Z version 5” you can not hand it over since he could mean “document Z version 5” of the team 1 branch or “document Z version 5” of the team 2 branch. It’s all about naming. “document Z version 5” is simply a not correct naming approach in the defined namespace.
In Subversion you can only do this limited, so that makes it simple to understand. Some concepts matched to this:
A version is a revision of a certain element. So e.g. wp-config.php version 5.
In a tool like ClearCase you can also see individual versions of elements and “commit” individual files (but also do atomic commits or change set or whatever).
In Subversion handling versions is more limited:
- a set of changes you make locally in one go you “commit” which means that that complete set of “changes” atomically are committed and the whole base gets a new version number. This is the version number you see in the WordPress subversion site.
- so you can not make locally more changes on 1 file and have them all treated as singular new versions as in clearcase. all changes you make locally to that 1 file or any other are submitted in one go and get that “unique new name”.
- if you have no access to the repository (rights) you can make a set of changes and save those in a “patch”. You can then send that patch to someone such as an integration manager or even a build manager who applies it to the repository. Tools like e.g. RTC also support “patches”. So one person creates a patch and another one applies the patch. You should consider this really as the word means “a patch” so not the default use case of development of code.
- instead of /branch N/hello.doc/version 25 there are also labels such as /branch N/hello.doc/LATEST or /HEAD. In some version management systems you can apply complex labels and then write scripts working on these labels.
working on a version
In Subversion the default use case is that you simply download all stuff to your harddisk from a repository checkout , work on the stuff and then commmit and then face all the changes other people made whereafter you resolve conflicts. These concepts you see in the GUI. IF you want to prevent someone else also editing your e.g. hello.doc then you LOCK it meaning: no-one else should be able to change it.
I REALLY don’t like that idea 🙁 IMHO that is very bad practice. for comparison and understanding: In ClearCase a checkout is more or less comparable to a lock and a checkin is a commit (in subversion checkin is an alias for commit). This is the default use case in ClearCase where it also supports hijacks which is the same as a subversion checkout but then on selected files. IMHO this is much cleaner. Furthermore even when you do the checkout in ClearCase it gives you 3 options: other people may not work on it (e.g. with word docs), other people may work on it if really needed and “everyone may work on it” (e.g. with source code files)
So… this is what checkout, lock and commit means in SVN.
components and baselining
In tools like RTC and ClearCase you can group elements into components. Powerful since these components are part of the name-space and get versions of their own by baselining them. So e.g. the component “WordPress” gets baseline release 4.53. These baselines are then objects in themselves which can then also get metadata such as “in test”.
However SVN does not have ANY this. So… :
In SVN (and so on the WordPress site) you see directories with numbers in an overall directory called ‘tags’. A workaround idea. You simply grab a certain repository and dump it (file based) into a directory tags/3.2.4. That’s it. It has no relation in the version management namespace etc… just a simple directory…. SIGH….. Impossible IMHO to do any configuration management with this kind of tool. So it is not a metadata object where you can script against and assign properties and do the wildest things no… its just a directory…………. In RTC for comparison you can make a ‘snapshot’ of a certain baseline to also support this use case. In ClearCase UCM you would make a new branch/stream of a a certain baseline and then ‘view it’. But making a baseline would be enough since if anyone would ever want to have to look into that baseline he would simply create a branch of it and view it.
This is not used in WordPress environment as far as I know but maybe I am wrong and there are teams doing this for the releases of WordPress to back port changes to older versions. So I don’t know maybe someone else knows.
This is used for the namespace tree. To have 2 teams working on the same code you can say “in english” team 1hello.doc and team 2hello.doc. Both teams then go working and after a while you have team 1hello.docversion 51 and team 2hello.docversion 23. (so team 1 made 51 versions and team 2 made 23 versions). Now you have the possibility to merge from branch team 1 to branch team 2 and you will get merges in team 2 but at the end team 2 will have all changes of team 1 (version 24) and the individual branches still show the work for each of them.
In RTC and ClearCase this is not used but a more advanced object called “streams” (for comparison). From a low perspective you can consider these the same BUT……. when you are in real life your branches will contain A LOT of stuff. So in the real world you would have to make notes, release notes, documentation etc… To enhance this a stream contains not only the “code” but also the “changes” so that you know that RFC23 was about version 34,32 and 56 and you can release them seperately.
IMHO if you want to setup things right then you give EVERY person one or more personal streams/branches. So they can checkin/commit and checkout from there and it bothers noone. only when someone is ready they “deliver” their stuff to e.g. the team stream and the team stream delivers to the integration stream etc… In WP possibly the releases are branches but for regular persons: they all work in the same branch. A disadvantage since “testing projects” are then in c:temp and not under version management and you can not have a group of people temporarily working on feature X that will only be needed in 5 releases time.
the ideal world and trade-offs
if you have team1hello.doc and someone copies in team2 ALSO hello.doc that this is BAaaaaad. Since now we have 2 elements with different ID’s where the user thinks they are the same but the system treats them as not the same. This is called ‘evil twins’ and you should never do this in such kind of environment. Always merge or base of branches.
If you understand evil twins you understand branches (why this is bad: because on a merge they will be treated as 2 different entities while you want them to be treated as the same) (or different kind-of behaviour in different systems). If a new user screws anything up, this is mostly it. ‘I just deleted hello.doc and copied it back in’ argh
SVN does not offer support for this BUT there are tools you can integrate with it to support some kind of integrated change management / ALM. In tools like ClearCase- UCM variant or RTC you can not change 1 letter without there being a defect, RFC, ticket, etc… In SVN when you a commit you can type a description for your atomic commit. Meaning: you should try to have you changes in “patchable” pieces in other words: do an atomic commit per defect/change to have somewhat that behaviour. (but ofcourse it is nowhere afterwards all linked together in a naming tree such as in the ClearCase database) (so that you can automate release notes or help the poor guy being deployment manager getting tons of new sets of code, changes, releases and trying to mingle it together with no real tool to give him any insight on what it actually is).
Since SVN does not support change management WordPress set up to use TRAC: http://core.trac.wordpress.org/ as you know because you live there 🙂
I feel TRAC is there because a real tool like ClearCase or RTC which has changes integrated in as objects (yes the one you program against) is missing. So you have a tool where you discuss and submit a “sort of ” change set to (while that concept is also missing). So these are the “patches” just a bunch of files without any of the metadata which you would expect in a good system (so I am now in Grumpy state). The number of TRAC is important since that is the overall ID in the naming tree linked to some changes.
This is something to write in a seperate blog article. In short: in the ideal world you would want to select your changes you want to ‘deliver’ (or another concept) and then don’t worry about files, directories (versions of). You just “deliver RFC 3 and 5”. This is how ClearCase UCM or RTC works. In SVN / base clearcase you ‘commit’ a bunch of files where we hope that you made the right decision. That is a big difference and an important one. (this is why SVN is mostly used together integrated with e.g. jira / clearquest / etc… to reach this behaviour). Patching …. is not delivering it is more from 1 stream to another as a uhm ‘patch’.
In other tools you this differently in SVN it is more simple: if you have code from a part which is not your own then you can treat it as external version managed and … to go back to the core concept: you mean that that part does not fall under you name space responsibility since it is all about naming. BUT even though it is external it falls under your responsibility.
In the GUI there is not workflow in the regular “right mouse” but it is defined in the project structure. So it is part of your definition.
This concept, if used, is defined in the IEEE CMP as required to define (See under)
Integration and Merges
As said. The paradigma behind SVN is to get stuff locally, do your work and then commit and then have the s***. In the GUI you do get though exactly the same tooling as most others. Here you should really understand three-way merging, two-way merging and the difference between conflicts that can be automatically resolved and conflicts that can not be automatically resolved. This last one then falls in 2 classes: those where the tool can propose you what the good end result would be and those in which it does not know what the end would be. You asked about the GUI but on the command line you get information files on what you should fix/merge before committing.
Lots more for a blog article. (e.g. Open Source Development versus Enterprise Development and build meisters and integration managers since you really have to make different choices here).
Last but not least the CMP
What you ask for is a Configuration Management Plan for WordPress. This is a IEEE document. Meaning: whatever of the millions of configuration management plans you find on Google they all are valid against the IEEE specified (several versions) of the CMP.
Just like (e.g. HTTP) RFC’s there is the IEEE CMP.
This plan contains defined sections such as “how to treat externals” and “how the namespace looks like, how we retrieve items and how we reproduce items”, roles, responsibilities etc…
From this CMP you can then create work instructions. Anyone wanting to know what the rules are can then read the CMP.
In an open source context often the role ‘configuration manager’ is missing. So you also miss the Configuration Management Plan.
Different from a public RFC (e.g. URI or HTTP) You have to pay for the IEEE standard document but… if you Google you will find it here and there.
In a delivery street you would have a team thinking about new business ideas. You have a maintenance department getting a gazillion production bugs in their system. You would have multiple teams working on the same code. and in each substreet you would have a requirements team defining requirements. An architecture team split in a functional team and an operational team ( use cases go to functional team and non functionals to the operational team). You would often have different releases parallel live in a unit test environment, acceptence environments, load and stresstesting environments, functional test environments, pre production test environments and production environment(s).
In all of them are versions that are all traced to each other.
one version on a specific test environment is linked to a set of versions linked to a specific RFC and this one is linked to a specific versions of a requirement. The requirement is then linked to a specific version of a testset. ALL fall under version management.
In WP with SVN/TRAC I have not found yet the requirements database and the versioning database of the requirements. (so that you can do impact analyses and see what code changes if you change 1 requirement)(and that in a new release you can print out which requirements have changed). I have seen individual items in TRAC where links are made to other individual items in TRAC in the comments. I have also not seen traceability between TRAC items and the code other than in comments. So it means people are doing a lot in their heads and it is very dependent on an active community or core developers since they have much of this in their brain.
But this is going far off topic grin
OSLC for ALM
Just one more note for this story: would it not be nice if there would be one package of standards for all of these application lifecycle management tools (ALM)? Someone thought of that and there are now standards so that all concepts are put on a higher abstraction level and then implemented in the tools. Google: OSLC for ALM. (so that all tools can talk to each other and for the user: that you understand them all by understanding the abstraction layer).
Even one step further if you have the time: the world is now heading for C/ALM, a next generation of products where the processes and the tooling is one integrated thing so that you dont have to wonder anymore what the process is. The first product in this generation is RTC. So if you understand SVN well or understand ClearCase or Jira or Trac or ANT or Agile or RUP or iRUP or whatever process, version management, change management, build management thing, you will need all of that to understand RTC because all of that is combined in one thing because they all tie in together and this on itself is interfacing through OSLC so that any of these older tools can “plug in”.
But now i am really off topic.
I don’t use (widely recommended) TortoiseSVN at moment, but turns out it has very extensive manual, available online and for download in multiple languages.
In its own words:
This book is written for computer literate folk who want to use Subversion to manage their data, but are uncomfortable using the command line client to do so. ( Preface )
This document describes day to day usage of the TortoiseSVN client. It is not an introduction to version control systems, and not an introduction to Subversion (SVN). It is more like a place you may turn to when you know approximately what you want to do, but don’t quite remember how to do it. ( Chapter 4. Daily Use Guide )
Pretty much what I was looking for, reading it now.
If you are using Windows you could try TortoiseSVN (http://tortoisesvn.tigris.org/). It doesn’t integrate with the IDE but it does integrate with Windows Explorer so you can right-click too check-in/check-out your code.
The best GUI one I have seen is
There is a great visual tutorial here based on mercurial
A lot of this depends on how well your IDE has svn and git integration that makes doing things easier, for instance Eclipse has a lot of tools but something like ultraedit ( which I used to use) has a strange version control gui and system.
The topic suffers from the boredom syndrome, at least for me it hard to learn the details due to this, I found watching youtube videos on the topic really helped the learning curve x100.