Loading...

All project content is available for reading, but you need to be a member of the project for Subversion checkout of source code, or to create/modify any information.
Login if you are a member. Apply here to request membership (open to all).

How To Contribute

We created this project for you, so that you could benefit from these modules, in your EPiServer projects. You might have saved lots of time and/or earned some money. The only thing we want from you is your contribution. We'd like any improvements to find their way back into the trunk, to create even better modules.

Preferred practice making contributions is as follows:

Contribution of minor changes

  • Create a ticket (or maybe a ticket for a bug/enhancment already exists), and enter information about the proposed solution.
  • Write, test and compile the code locally.
  • Most members (those that behave) have read/write access to all source code. Commit the changes to the repository, and make sure you add comments when committing, with the neccessary information, preferably linking to a ticket.
  • A peer preview should be done to verify the code, if possible. Module "owners" will usually monitor the timeline.
  • Ticket should then be closed

How to contribute a new module

As a registered member, you already have access to commit changes to the Subversion repository and to create wiki pages. In order to keep the repository structure consistent, and to make it easy to find and download your module, we have some guidelines we'd like you to follow.

If you're unsure about anything related to this, contact us directly, and we'll do our best to help you out.

The process in brief

  1. We agree on a folder structure for your module.
    For an example: MyCompany.ModuleName\6.x\ for a module for CMS 6.
    We can help you create the inital folder structure. Browse the source to get an idea on the structure.
  2. You Checkout (using a Subversion client) the folder locally, add your files, and Commit the folder structure with the files to the repository.
  3. You create a set of wiki pages to describe the module
  4. You add a download page for the module, with a link to a Manager installation package to make it easy to install the module (for CMS 6 modules).
  5. Adding screenshots and screencasts will help people understand what your module does. A screenshot is worth a lot, and tells much more than a feature list.

The folder structure

To keep things tidy we try to follow some kind of naming scheme for all modules.

If you look at the source root you can see that most of the modules are located in a root folder with the name of the module, often with a company prefix. The prefix is entirly optional. See it as an opportunity to market your company that have invested time in letting you do the module, and contributing it.

When you have decided on a name, there are a few ways to create the file structure. Here is a quick walkthrough adding your project using TortoiseSVN:

Creating the repository

  1. Create the following directory structure (of course changing the module name), somewhere on your harddrive. This example assume you create a folder directly on the root of your C: drive.
    \MyCompany.MyModule       <-- To distinguish it among the other projects
      \6.x                    <-- For CMS 6 modules, use 6.x if the module is for v6
    
    Your project files will be placed directly inside the ´6.x´ directory.
  2. Copy the Visual Studio project into the 6.x directory. The project file will then be directly below the ´6.x` directory.
  3. You now have the layout, next it is time to add this to the EPiCode repository
  4. Open Windows Explorer, browse to the folder above \MyCompany.MyModule, right click the \MyCompany.MyModule folder and select SVN Checkout
  5. In the Url of repository textbox, enter https://www.coderesort.com/svn/epicode/
  6. Click the "..." button after the textbox. This will open the Repository Browser.
  7. It will show the root of the EPiCode repository. Right click the folder and select Create Folder.
  8. Name the folder with the company name and module name (MyCompany.MyModule). Make sure you enter a comment and click OK.
  9. The Checkout directory box should now say C:\MyCompany.MyModule (given you put the directory directly below the root of the C-drive, which might not be a good idea, but used here for simplicity.).
  10. Click OK, and ignore the warning you'll get about the directory not beeing empty.
  11. At this point you have Checked Out the repository to your local working copy.
    This means you have a working copy on your hard drive that no one else can see. No files have yet been sent to EPiCode.

Adding files

Adding files to the repository is easy. We'll do it the "hard" way here, to explain the process, and make sure you do not commit any files that are not really neccessary to keep under version control.

A Visual Studio project usually consists of quite a few files that you do not want in the repository. You can always delete files at a later time, but getting it right the first time is better, so we'll spend some time doing it correctly.

A typical Visual Studio web project contains a few files that are unique per-user, but always named the same. We don't want these added, as they will always be in conflict with other users' files.

The same goes for intermediate files, like those in the /obj directory, produced by the compiler. When you compile the project, you generate an assembly in the /bin directory too. There is no explicit rule if this assembly should be excluded or not, but if your project has many developers you'll find that excluding it will lead to fewer conflicts.

The following process shows how to add files to the repository (given you have followed the steps above):

  1. In Windows Explorer, navigate to C:\
  2. The \MyCompany.MyModule web folder should have a TortoiseSVN icon, but not the folder and files inside of it, as they have not been added yet.
  3. Right click the \MyCompany.MyModule folder, select TortoiseSVN->SVN Add...
  4. TortoiseSVN will show you a long list, of all files in all subdirectories. Make sure everything is selected, and click OK
  5. Now it is time to "regret" adding the files we really don't want in the repository (Note! You could have just unticked the files in the preceding step, but if there are many files, adding them all, and then "regretting" this before the actual commit is quicker.
  6. Select the following files and directories in the web folder (ctrl + click lets you select different folders and files)
    • obj
    • any .user, .sln, .suo files
    • license.config
    • + any other folder or file you do not want to add to the repository
  7. Right click any of the selected files or directories, select TortoiseSVN->Revert. This will undo the addition, before anything is committed to the repository.
  8. Right click the same files and directories (separately) and select TortoiseSVN->Ignore.
  9. Now you're ready to commit all the files to the repository
  10. Navigate up to above the \MyCompany.MyModule directory, right click it and select SVN Commit. Don't forget to comment.
  11. Your files have now been added and committed to the online repository. The files are officially under source control. Check the timeline to see what you have just done.

Most important, don't be afraid to experiment, ask or commit. Everything is being taken care of very carefully by Subversion. We can clean up and fix almost any problem by reverse merging a troublesome commit. We have done it before, and will have to do it again - for sure, and we don't mind. We'd rather have lots of people messing around in the repository, learning how to do this correctly than none because they are afraid to screw up.

Practising

As a registered member on EPiCode, you have a CodeResort login, which means you've got access to the sandbox project, where you can play as much as you want. That is why it is there.

We sincerly hope you take the time and make the effort to contribute back to the project!