Checkin In? Hints & Etiquette

Each subscriber is encouraged to check in modifications to the MacApp sources that fix bugs or implement enhancements.

Checkin Procedures

Here is the checkin process each subscriber should use to help insure that all changes can be identified, that the staff can understand the purpose and approach for each change, and that each change will work as expected.

Prior to your checkin:

  • Send a proposal via e-mail to explaining the purpose of your changes. It should explain the feature to be added or the problem to be fixed. In this way everybody will know your change is coming,and you will be able to find out if anybody else is trying to do the same thing. A good e-mail will include the following:

- A verbose paragraph detailing the overall purpose of the change or enhancement.
- A list of files to be changed and a short descriptoin of each change.
- Any special notes about gotchas, known bugs or limitations.

  • Make sure that each source file to be checked in has a change history comment. Include the date (in mm/dd/yy format) and your initials and follow the existing format to satisfy some existing MPW and Perl scripts that we occasionally run for maintenance.

  • Note that this e-mail is sent to the MacApp-Dev mailing list. This means that you will need to be a subscriber to MacApp-Dev. For information on subscribing please go to the MacApp-Dev mailing list web page.

Once you are ready to perform the check-in:

  • Enter a comment in the change history for each source file, following the established MacApp format.
  • Update the release notes and documentation.
  • Get the most recent revisions and test your changes thoroughly before checking in.
  • Use the "Find Lurkers" command to find all the modified and new files.
  • To check in a file, simply select it in the Finder-like window of MacCVS Pro and choose the "Action:Commit..." menu item.
  • Provide a detailed comment when checking in. This comment will accompany the e-mail notification that is sent to all subscribers. Ideally, this comment will be the same as your update to the release notes.

When you receive a notification, please, if you have the time, checkout the changes and review them.

WARNING: "If you are not careful, you can erase someone else's changes. CVS has some safeguards in place that try to minimize the possibility of this happening, but you still have to use common sense. We recommend that you use the Status:Compare With Original command on the file (if it's a text file) to first view the differences between your local file and the repository copy before you commit the changes." - From mcvcvs.org.

Notifications

Whenever one or more files are checked in a notification e-mail will be sent to all subscribers. This e-mail will contain an entry for each file checked in and will include the following information:

  • The name of the file changed.
  • The name of the person making the change along with their contact information.
  • The directory containing the file changed.
  • The module name (always 'macapp.15.1.1').
  • The date the change was checked in.
  • The new version number and the old version number.
  • The tag associated with the checkin.
  • The check in comments.

Here is an example of the message that is sent out:

 
CHECKED IN: 'MyApplication.r'
User: Mike Rossetti
(rossetti, rossetti at mac.com, +1-801-TRY-MIKE, frmwrks)
File: MyApplication.r
Directory: MacApp/Examples/A-Z/Appearance/Grayscale Appearance Views
Module: macapp.15.1.1
Checked In: Fri Jan 4 16:35:48 EST 2002
New Version: 1.1.1.6
Old Version: 1.1.1.5
Tag: 1.1.1
Comment:
 
Completely reworked the spellings converting everything to pig latin.

Branches

You may occasionally find a need to create a branch within the repository. Branches allow you to isolate changes that you are not quite ready to check in to the main trunk of the project. Once you are confident in the changes you have made you can merge the branch containing those changes into the main trunk. You may consider asking others in ClubMacApp to review your changes before merging them into the main trunk.

To create a branch:

  • Select the changed files and use the "Tag" command to define a branch. There is a "Branch" radio button in the Tag window that allows a branch to be created. Enter the name of the branch and press OK.
  • Once you have tagged one or more files using "Action:Tag..." you will need to update your local copy to reflect the tagging. Do this by choosing "Action:Update To..." The "Update To" window will be presented. In this window specify the mode as " Retrieve Sticky (Tag)" and type the name of the branch which you specified above.
  • Use the "Commit" command to check the files in on the branch.

You can Tag an entire directory structure but be careful when doing this.

To check out a branch, select the file or directory for which the branch is desired and then choose "Action:Update to..." and providing the name of the desired branch.

Important Points

Please be careful about the following issues, that could affect the integrity of the repository:

  • Do not use the command line CVS.
  • Do not check in .DS_Store or .FBCIndex files.
  • Do not perform imports.
  • Add is used to incorporate new files, not to check in modified files.

Let us know if there is any administrative actions required to correct any problems in the repository -- please do not attempt to fix such problems on our own.