This project is read-only.

Before You Start Writing the Code

It is always tempting to jump into coding something right on the spot and then share your work as soon as possible so others can enjoy what you have done and start using it immediately. However, frequently in this "gold rush” we may skip on backward compatibility concerns, security threats or possible upgrade issues for the sake of the development speed which is something that brings a lot of hassle to anyone who started using your work. This editorial effort is dedicated to minimize chances for such issues to happen by outlining and describing some engineering practices we have learnt along the way. Anyway, if you find some of these practices to be not quite adequate or beneficial please do step up and advise us something better because you voice does matter!

So lets get started with some practices we believe to be good to use for your contribution efforts to WebsitePanel project…

Folders Structure

It is always good to keep things organized and in shape. So do we with the folders structure being used for the development process that frequently incurs not only software programming effort but also some Mercurial repository manipulation work (eq. pulling and pushing changes, merging, working with branches and etc.). Here is the proposed folders structure that I use to organize my development workspace and hope it will work for you:

\rd\WebsitePanel\main – contains stable stream (eq. default branch)

\rd\WebsitePanel\dev – contains development stream (eq. dev branch)

\rd\WebsitePanel\qa – contains quality assurance stream (eq. qa branch)

Hint: the shorter path you have the more pleasant your user experience is (please do keep in mind 260 characters limit for a path string in Windows including file name - see this article if you’re curios).

Setting Up Your Mercurial Environment (.hgrc)

To save some amount of keystrokes and label your work recognizable under your own Mercurial identity, you should configure .hgrc file for the environment. Lets start with the PowerShell command that creates this file for you in your User profile folder:

New-Item –Path ~/.hgrc –ItemType File

image

Then you need to tweak the content of the file with some settings to set the initial configuration for your entire Mercurial environment. To quickly start edit the file you may type in the prompt the following command and press Tab (to expand the path shortcut first) and then Enter (to execute the command itself):

notepad ~/.hgrc

image

The very least amount of settings you should have in your .hgrc file is the only one setting in [ui] section which Mercurial is going to use with an every operation that modifies the state of the repository to name the change under (do not forget to save your changes!).:

image

* Hint: if you are curious what other settings available in [ui] section to adjust the Mercurial environment please use refer to the following article hgrc :: [ui].

Now you are good to go to the next section! Smile

 

The following list is a list of practices we have learnt and find very helpful to exercise while working on a project with the team distributed around the globe. So please take your time to read them through and try to apply these when you work with the source code for the project. Some of these take less time to get into than others but eventually you will be good in all of them.

One Commit

One reason for the changeset’s existence (a bug, feature work and etc.), this schema also empowers you with a great rollback tool of Mercurial in case of any errors.

Keep Your Local Repo in Sync

Please do pull from the project’s remote repo on a daily basis (or more frequently as appropriate), if someone has just sent a change that is incompatible with what you are currently working on then you notice this conflict almost on an instant (because you sync frequently) which is good since your work has not grounded yet and either you can adjust your code or you can contact the owner of the changeset that gets you in trouble to adjust his work appropriately.

Frequent Commits

Do not keep the entire scope of your work in progress “smokin” for 2, 3 and more weeks locally (see ‘Keep Your Local Repo in Sync’ rule that lights up the case as well), try to arrange it that way so you can send your changes at least every week. However, if scope or impact of the work is really massive, please do split it up for smaller chunks so they can be either safely committed one-by-one or shared among other developers in case if you need any help or assistance.

Conscious Commit Comments

The conscious they are, the easier yours and others developer life is.

Build Your Work Before Commit

Do build the entire solution locally when you are about to commit your changes to the repo – re-integrate your work into a clean copy of the branch you are working on and build the whole solution when you are about to commit. The benefits of doing this all the time are not so obvious but they are very valuable and here they are:

  • Helps to catch missing references to external assemblies (those have been just added, if any);
  • Helps to catch cases when for some reason you re-targeted an existing reference to assembly and forgot to update the project file settings or make new version of the assembly a part of the changeset;
  • Helps to catch cases when the change you are about to commit is incomplete or missing some crucial parts to be able to compile successfully;
  • Gives you confidence that your change will not break the build;

Beautify Your Code Wisely

Some smart-n-savvy Visual Studio plugins provide you tools to replace spaces with tabs and vice versa for a file to match you dev environment settings and beautify source code layout – please do not mix your work in progress with these layout cosmetic changes in a file as if you do then neither literally no one will be able to review your work nor automatic merge algorithms of Mercurial will be able to help you with the merge if there is a conflict. I had been doing this in the past and feel guilty about it (trying to improve bad habits now). However, I am not saying that these cosmetic changes should never happen but instead I do advocate to separate them from a way more serious things to be committed (see ‘One Commit’ rule that lights up the case as well).

Code Review via Patches

It takes both yours and reviewers’ time but pays off x10 (sometimes even more Smile). We will be doing a separate article for this, so keep your eyes on it.

Working on an open-source project with the team distributed around the globe requires some discipline from you to follow certain practices that are essentially a safety net to catch issues early before they went into production.

We hope this all makes any sense for you and stay tuned for more info! Smile

Last edited Jun 11, 2012 at 6:21 PM by ptsurbeleu, version 1