How to submit your changes to modules or the core?
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 .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.
