Guidelines for working with the Puppy SVN repository

UsingeSvn simplifies working with Subversion.

Foreword

Avoid deviating from these guidelines. Only deviate when there is no other alternative. Remember that this is a shared space

Project Organization

One of the most important aspects of a repository is establishing a consistent file structure.
For puppy each repository can have multiple projects and each project MUST have trunk, tags and branches subfolders

e.g.
puppy-miniapps repository

Include README file

Always include a README file with your project at the root of your deliverable tree structure.
It should include at least the following:
- A description of the project.
- Who are the original and current authors
- Explain how to set up the development environment required to modify, compile and deploy each deliverable.
- Any dependencies.
- Licensing: Is it covered under the same license of Puppy or does it have it's own license?

Do not check in third party source or binaries

This repository is only for Puppy specific code. Including patches to the third party code
Third party code must have its own repository. The project for the patch must get the source from the original repository as part of the environment setup process.

Name based on purpose

Always use the same name for folders with the same purpose, e.g.: src, install, config, shared, doc, etc.
Investigate how it has been named in other projects.

Don't check in garbage

Don't check in temporary files or compiler generated intermediate files.
Adding unnecessary files to the folders makes slower to check out the project and to make sense of the content of the project.
They may even overwrite other contributors preferences.

Check in all required files

Check in all files required to recreate a deliverable: Source files, build configuration files, build scripts, instructions for third party libraries,etc.
That is one of the main purposes of source control: To have the ability to recreate any build at any point in time.

Source control should match Development environment

Most of the time when the source control and development environment folder structures match, setting up the development environment is as easy as getting the source files to the default location.

Tracking projects

Tag your project as soon as you have a test candidate and after that increase the build number for each test/release candidate.
If you label each candidate, you will always be able to go back to help you solve problems, e.g. a bug is found and you are sure that it was not happening in previous revisions. Remember, if you don't have the source, you cannot debug.
The added advantage is that your final deliverable will always have a label.
We don't usually know which build will go into 'production' until it is released.

Standardize tag names

Choose a standard for naming labels.
The tag must identify the deliverable and the version. e.g. networkwizard-2.1.0.134

Only check in what you modified

Only check in files that you have consciously modified.
If the status shows that a file has been modified, confirm what the changes were before checking it in.

Add comments when checking in

Always add a meaningful short comment when checking in files.
Comment on what you solved (e.g., bug log #, or new functionality description). Remember that by using the comparison feature in Subversion you can always find out what you changed.
Adding comments will help you when you are trying to roll back changes or when you need to remember how or when you solved something. It will also help other people understand the history of the project

Check in frequently

Check in your changes in small increments. A recommendation is to check in one change at a time.
Frequent check ins have the following advantages:
- It makes it easier to remember what changes you are checking in
- It makes it easier to track your changes.
- It helps making sure that you have a working version
- It allows other contributors to integrate your latest changes frequently.

Only check in files that you have tested

Never check in files that do not compile or execute or that fail the most simple test.
Remember that other people may be refreshing their development files frequently.

Refresh your sandbox frequently

Update your project from the repository frequently. This will guarantee that your changes are in sync with other developers' recent changes.

Build frequently

(or test your script frequently) Build frequently using checked in code.
This guarantees that you always have a testable version of your software either for demo, walk through or release purposes.

Don't leave files checked out overnight

When you stop working for the day, check in the files you have been working on unless, of course, you are actually working overnight.
Files under source control are backed up frequently. Files in your computer are not.

Always refresh (update) your sandbox before modifying

Always refresh your environment before making modifications to it.
When you don't, you run the following risks:
- You increase the risk of collisions with other people's changes.
- Someone else may have already fixed or modified what you are planning to modify.

Delete obsolete files

When a file becomes obsolete delete from the repository. This will prevent confussion. The deleted files will still be available in older revisions.

---

CategoryDevelopment