next »

[calguy1000]

Many of us want minor tweaks, here and there for the various modules we use on our website(s), and occasionaly to the core.  Sometimes those tweaks aren't so minor. 

Many of you have been skilled and/or adventurous enough to dive into the php code and do it yourself.  Many times, those good ideas are not shared, and are not available to the masses. This means that each time a new version of the module, tag, or core comes out you must re-apply the modification and re-test, making upgrading difficult and painful.

Also, many times adventurous developers send a new copy of the <whatevermodule>.module.php file in it's entirety,  with numerous changes in it, which makes it difficult to the project administrator to analyze, and compare against the current live version.  This makes it difficult for the administrator to include in the main project as he has to do reverse engineering, testing, documentation, and integration.

This message will propose (what I think) is a good practice for submitting your own changes for a module, tag, or the core, to the lead developer, if you don't have SVN commit access.  Following these steps as closely as possible will make it easier for the project admins to analyze your change, comment on it, and then potentially integrate it directly into the project.


The steps:

a) Discuss your potential change with the project admin(s), or others in the forum or IRC channel
The developer of the relevent module, tag, or other project may have ideas, comments, or concerns about your potential changes, or may point out a better ways of accomplishing the same task.  He or She may also have standards that they are trying to adhere to in their code, or other procedures that they want you to follow when making patches.  It is always good to communicate (if possible) with the project administrator(s), before digging too far into a modification.

b) Check out the latest svn version of the module
Checking out the latest version of the code is always importent.  Developers frequently commit changes to the source code repository and acquire a few of those changes before issuing a file release.  Therefore, the status of the repository could be quite different from the latest file release.

The forge has an "SVN" tab for each project, which provides clear instructions on how to checkout the latest version of the code.  Also on the forge are instructions on how to use SVN for different platforms.     

c) Make your changes
Here you implement your ideas.  Try to keep make your code as similar as possible to the way the original developer(s) have implemented the existing code, and document your code well.  Here is where it is extremely important to communicate with the project administrators as much as possible (can I say that enough?)

d) Test them thoroughly
This is the tough part, but it's equally as important as the other steps.  Please make every effort to test your new code properly, and regression tests are also important, as you want to minimize introducing any new errors.

e) Do an "svn update" and go back to step "d" at least once
If your patch has taken some days to prepare, it is possible that more changes have been committed to the source code repository.  You will need these changes merged back into your code to properly test.  This can be done with the "svn update" command.  An equivalent command exists for tortoise svn.


e) Prepare a patch and the relevent documentation
Preparing a patch is a simple process, and simply involves issuing a "svn diff > patchfile.diff" command (from unix), See the forge for instructions on how to do this with tortoise svn.

f) Upload the patch to the "Patch Tracker" for the relevent forge project
Each newly created forge project has four trackers, one of thse is for patches.  Here, you can submit a new tracker entry, attach the patch file created above, and describe your changes.

Conclusion
If you don't have SVN commit access, then these steps provide a good way to create patches that are more easily handled by the project admins.  If you have good ideas, most of the module developers are all to eager to find help for their various projects, and will usually grant you svn commit access.  Most of the steps for working directly with the forge are the same however.  I hope this document makes it easier to allow you to get your changes into the project of your choice.

Again, your comments are welcome.

[calguy1000]

It was brought to my attention that some of you budding php hackers out there may not be aware of SVN, what it is, or how to use it.  So here comes the 5 minute tour.  This is not a complete howto, or a complete set of documentation, but is designed to introduce you to source code repositories in general, and svn specifically, what they do, and how developers would typically use them.

SVN (ir Subversion) is an open sourced source code repository tool.  It's designed to allow multiple developers to work on the same set of files essentially simultaneously, and to keep track of the changes in the code over time, for tracking, testing, and reversion purposes..    Similar (but not as good) products are RCS, SCCS, CVS (and lots of commercial ones).

There are a number of SVN clients available for download, or many linux distributions come with them automatically installed.  For windows, the favorite so far is "Tortoise svn", and infact there's a document about using that svn client with the cmsms forge here: http://dev.cmsmadesimple.org/docman/view.php/48/12/tortoisesvn.htm

For further instructions, please refer to the subversion manual(s), and help documentation.

Starting coding with svn

Checking Out:
To get started coding with svn you must first "checkout" some code.  You will be given a url that specifies the location of the repository, infact if you check out the "SCM" tab of any project page in the forge dev.cmsmadesimple.org, you will see the SVN url and the instructions for accessing it.  On unix, via the command line, this command is usually:

svn checkout <url>

At this point you're ready to start doing whatever you need to do.

Checking Status:
From time to time, as others can commit and modify files you will need to check what has been done.  This is accomplished with the

svn status

command.  It will tell you which files have been added, removed, locally modified, or modified by others, but will not make any changes to your files.

Merging:
Once you know what will be done, you can update your local working copy with the files that have been added/deleted, or modified by others.  This is done with the

svn update

command.  This will automatically merge the changes you have made with the changes made by others, into your working directory.  Note, this does not commit anything to the repository.

Adding files
If you create a new file that needs to accompany the other files in the source tree, you need to use the

svn add <filename>

command.  This marks the file for addition, but does not commit it to the repository.

Removing files
For removing files, you use the

svn remove <filename>

command.  This will remove the file from the local filesystem and mark it for removal from the repository (don't worry about removing files from the repository, they can always be brought back later).  This command does not commit anything to thre repository.

Getting a patch
Sometimes you don't have write access to the repository, or you want to see what has all been changed.  the

svn diff

command can be used to create a summary of all of the changes in the working directory.  You can send the output from this command to a file, and this is called a "patch file", as it can be used by other users to update their code.

Committing files
After you've completed your modifications, (and done the appropriate testing, of course), if you have access, you may commit your code.  This is done with the

svn commit

command.  You will be asked to describe all of your changes, and then all of the files you have modified, added, or deleted will be committed to the repository.  You are then ready to begin the development process again. 
Note:  You may have to do an

svn update

before committing your changes, as the repository will not allow you to commit changes if your local working copy is not up to date.

Conclusion
There you have it, that's the 5 minute tour of svn, and source code maintenance in general.