Forge Tips¶

Collected Tips about using the-Starport Forge -- Bullwinkle

Tips:

• Forge Tips
• Sub-Projects
• Forums
• Whats New -- Keeping Track of Your Team
  • Activity Page
  • Watches
• Using the Wiki
• Files Module
• Version Control
  • SubVersion Most-Used Commands
  • Check Out
    • How to Get a Working Copy of a Project
  • Troubleshooting

More Tips:
How to Build a .DLL from a .RC Script

_Adventures of Trent_ home page

Sub-Projects¶

You can add and manage your own sub-projects as you like. There are many uses for sub-projects. One that we found immediately useful was to keep our main project Public, and create a Private Development sub-project.

That way, the team can work in privacy, and still publish finished work in the Public project:

Main Project (Public)

• Wiki
• Files
• News

Dev Sub-Project (Private)

• Wiki
• Forums
• Issues (bug tracker)
• Repository (SubVersion Version Control)
• Activity
• Files

.

Forums¶

Want to talk with the team when members live in different time zones? And keep track of the conversation, just in case somebody says something important? But you don't want to fill up the-Starport's forum with off-topic chatter?

Then project Forums may be for you. They work very much like the-Starport's main forum, except that you have more control over them. A Forum in your Public Project will be open to all, while a Forum in your Private Sub-Project is only readable by your team.

Use the Activity Page and/or Watches to follow the topics in your forums... see "What's New", below.

.

Whats New -- Keeping Track of Your Team¶

If your team is busy making updates to your mod or project documentation, then it can be challenging to keep track of who has changed what recently. Two features of the Forge help you to see What's New:

Activity Page¶

Look at the Activity Page for a quick way to see What's New in your project. Use the filter checkboxes on the right to select which items you want to see on the Activity Page:

.

Watches¶

Many of the project pages can be "Watched", which means that you will get an email when that page changes.

For example, if you keep track of team chatter (questions, answers, decisions) by using a private Forum, then you might want to receive an email when a team member makes a post. Wiki pages, Issues, and other pages can also be Watched. To set a Watch, look for a small "Watch" button in the upper right-hand corner of the page:

.

.

Using the Wiki¶

The Wiki on the Adventures of Trent Forge is powerful and easy to use. You can make many kinds of web pages with it.

Use the buttons at the top of the page to insert formatting codes, or just memorize them.

If you want to create a new page, simply create a link to a new page with a unique name (in Edit mode). Then, click the link (in Read mode) to create the new page.

This is a link in Edit Mode:

.

2) To Cancel your editing session and return to Read mode, click Wiki on the Forge toolbar:

.

You should now be in Read mode. Simply click your new link to create a new page.

.

Files Module¶

The Files module gives you a place to host files for the public, such as a version of a mod. Once uploaded to the Forge, Files cannot be renamed or moved. The reason for this is that each file in the Files module gets a URL so that you can link to the file from elsewhere (such as the-Starport forum, for example).

In order to keep your Files organized, you can use Versions to mimic sub-folders. In Settings, Create a New Version:

.

The Version Name is what users will see in the Files listing as a header -- similar to a folder.
The Optional Wiki Page is the name of a page in your project's Wiki that is linked to this Version's Files.

.

Go to the Files Module, and click New File to upload a file.

.

In the New File dialog, use the pull-down menu to choose the Version/Folder where you want the file.

.

Version Control¶

The coolest and most important feature of the Forge is Version Control (via SubVersion - SVN). A Version Control System (VCS) allows team members to work on the same code without interfering with each other. A VCS offers:

• Automatic backup of every change made by every developer on the team. (Well, every committed change.)
• Semi-Automatic Merge(*)
• Encourages good documentation and good communication between team members.
• Ability to mark a "version", which includes all of the source files required to make that version.
• Ability to roll back changes (in case you try something that does not work).

SubVersion is a popular Version Control System (VCS). The server side is SubVersion. The client side can be one of many client tools. TortoiseSVN is popular for Windows users because it is integrated into the Explorer (does not require a special control panel).

(*) If you are familiar with other VCS systems, then you will notice that SubVersion's "Check Out" is different. Instead of locking a file on Check Out, SubVersion allows developers to freely check out the same files. In fact, SubVersion encourages multiple-user Check Out by Checking Out entire folders rather than individual files.

The underlying assumption is that the two developers will be working on different parts of the file, so that their work should not interfere with each other. This is not always a good assumption, but it avoids the problem that other VCS systems have with forcing developers to wait for each other.

If two developers edit the same file at the same, SubVersion automatically helps the developer to merge his/her changes. This reduces conflicts while allowing maximum team productivity.

Obviously, poor team communication can cause this feature to backfire. Two developers working on the same part of the same file (or who make sweeping changes to the entire file), can create a difficult Merge. If this happens, conflicts will have to be sorted out the old-fashioned way... with a careful manual merge.

SubVersion Most-Used Commands¶

CheckOut
Get a project (or sub-folders) from the server. Used when getting a new project. Puts a copy of the project tree in your "working copy" folder.

SVN Update
(or Update to Revision) Update your working copy with the most recent files from other team members. An Update could over-write changes you have made, so be sure to Commit any changes that you want to keep.

SVN Commit (CheckIn)
Update the server with changes you have made. Creates a minor revision number every time any team member commits. Note that it is normal for revision numbers to grow quickly.

Merge
Compare (or Diff) your changes with the changes on the server. A Merge will automatically be triggered if you and another developer both Commit changes to the same revision of a file.

.

Check Out¶

How to Get a Working Copy of a Project¶

1) First, you must know the project's nickname on the Forge server. Let's use FLSES as an example, because it was asked about on the-Starport forum. Browse to the FLSES project page, then look at the end of the URL. The nickname is "flses":

.

2) In Windows Explorer, make a folder where you want to put the FLSES project tree:

.

Note that I put the folder in my FLMM\mods tree. That way, I can easily Commit changes as I develop the mod, which makes it easier for other team members to keep their Working Copies up to date.

.

3) Right-click the folder and select "SVN Checkout":

.

4) In the Checkout dialog, enter the URL of repository: http://svn.the-starport.net/flses. Leave everything else at their default settings:

.

5) Click "OK"

If you are prompted for username and password, use your Forge credentials.

TortoiseSVN (TSVN) should then fill your selected folder with the newest revision from the FLSES SVN Repository.

Notes

• Don't worry... SubVersion CheckOuts do not lock anything. "Export" does nearly the same thing as Check Out. The difference between "Export" and "Checkout" in SubVersion is that a CheckOut adds hidden .svn folders which SubVersion then uses if you ever CheckIn a modified file. Those hidden .svn folders are required for TSVN to manage your Working Copy.
• (Note that SubVersion CheckOuts are different than other Version Control Systems which lock Checked Out files.)
• You should Check Out into an empty folder (because TortoiseSVN (TSVN) will just download a copy from the server anyway).
• Theoretically, TortoiseSVN can Check Out into a folder that already has a copy of your project files. However, TSVN still has to download from the server in order to compare the file on the disk with the server version, so you gain nothing by doing that.
• If the Check Out fails before completion, just do an "Update to Revision" to continue the Check Out. Repeat until the Update completes with no errors.

Troubleshooting¶

If you have problems using SubVersion (SVN) or the TortoiseSVN (TSVN) client, then here are some tips:

• The server is always right.
• If the server is not right, then make it right by Committing your changes. You can Commit Deletes and Renames as well.
• If a Check Out fails with an error message, do an SVN Update (same as "Update to Revision") on the same folder. This will continue the Check Out.
• If an Update fails, repeat until it finishes without error.
• Clean Up looks for errors in your Working Copy and resolves them automagically.
• If Clean Up fails with an error, then delete the hidden .svn folder in the offending folder and then run Clean Up again. WARNING: Deleting the hidden .svn folder destroys the link between your Working Copy and the Repository. You MUST do an SVN Update to repair the link.

.

.

.

.

.

Last edited by Bullwinkle 2010-05-11

.

.

.

.