Freelancer Community Network

ForgeTips » History » Version 33

Bullwinkle, 06/05/2010 12:37 AM

1 4 Bullwinkle
h1. Forge Tips
2 1 Bullwinkle
3 1 Bullwinkle
Collected Tips about using the-Starport Forge -- Bullwinkle
4 2 Bullwinkle
5 20 Bullwinkle
{{toc}}
6 33 Bullwinkle
[[aot:HowToBuildDllFromRcScript|How to Build a .DLL from a .RC Script]]
7 20 Bullwinkle
8 8 Bullwinkle
h1. Sub-Projects
9 1 Bullwinkle
10 8 Bullwinkle
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. 
11 1 Bullwinkle
12 8 Bullwinkle
That way, the team can work in privacy, and still publish finished work in the Public project:
13 1 Bullwinkle
14 8 Bullwinkle
*Main Project (Public)*
15 8 Bullwinkle
* Wiki
16 8 Bullwinkle
* Files
17 8 Bullwinkle
* News
18 1 Bullwinkle
19 8 Bullwinkle
*Dev Sub-Project (Private)*
20 8 Bullwinkle
* Wiki
21 8 Bullwinkle
* Forums
22 8 Bullwinkle
* Issues (bug tracker)
23 8 Bullwinkle
* Repository (SubVersion Version Control)
24 8 Bullwinkle
* Activity
25 8 Bullwinkle
* Files
26 1 Bullwinkle
27 22 Bullwinkle
.
28 9 Bullwinkle
29 9 Bullwinkle
h1. Forums
30 1 Bullwinkle
31 9 Bullwinkle
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?
32 9 Bullwinkle
33 9 Bullwinkle
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.
34 9 Bullwinkle
35 9 Bullwinkle
Use the Activity Page and/or Watches to follow the topics in your forums... see "What's New", below.
36 18 Bullwinkle
37 22 Bullwinkle
.
38 18 Bullwinkle
39 21 Bullwinkle
h1. Whats New -- Keeping Track of Your Team
40 1 Bullwinkle
41 8 Bullwinkle
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:
42 1 Bullwinkle
43 8 Bullwinkle
h2. Activity Page
44 5 Bullwinkle
45 8 Bullwinkle
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:
46 5 Bullwinkle
47 8 Bullwinkle
!Activity01.png!
48 5 Bullwinkle
49 22 Bullwinkle
.
50 22 Bullwinkle
51 8 Bullwinkle
h2. Watches
52 5 Bullwinkle
53 1 Bullwinkle
Many of the project pages can be "Watched", which means that you will get an email when that page changes. 
54 8 Bullwinkle
55 24 Bullwinkle
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:
56 5 Bullwinkle
57 8 Bullwinkle
> !Watch01.png!
58 3 Bullwinkle
59 20 Bullwinkle
60 22 Bullwinkle
.
61 22 Bullwinkle
62 22 Bullwinkle
.
63 22 Bullwinkle
64 20 Bullwinkle
h1. Using the Wiki
65 1 Bullwinkle
66 1 Bullwinkle
The Wiki on the Adventures of Trent Forge is powerful and easy to use. You can make many kinds of web pages with it.
67 1 Bullwinkle
68 1 Bullwinkle
Use the buttons at the top of the page to insert formatting codes, or just memorize them.
69 1 Bullwinkle
70 1 Bullwinkle
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.
71 1 Bullwinkle
72 1 Bullwinkle
This is a link in *Edit Mode*:
73 1 Bullwinkle
74 1 Bullwinkle
!Wiki01.png!
75 1 Bullwinkle
76 1 Bullwinkle
77 22 Bullwinkle
.
78 1 Bullwinkle
79 1 Bullwinkle
2) To *Cancel* your editing session and return to Read mode, *click Wiki* on the Forge toolbar:
80 1 Bullwinkle
81 1 Bullwinkle
82 1 Bullwinkle
!Wiki02.png!
83 1 Bullwinkle
84 1 Bullwinkle
85 1 Bullwinkle
86 22 Bullwinkle
.
87 1 Bullwinkle
88 22 Bullwinkle
89 1 Bullwinkle
You should now be in *Read mode*. Simply click your new link to create a new page.
90 1 Bullwinkle
91 2 Bullwinkle
92 2 Bullwinkle
!Wiki03.png!
93 2 Bullwinkle
94 8 Bullwinkle
95 1 Bullwinkle
96 22 Bullwinkle
.
97 22 Bullwinkle
98 21 Bullwinkle
h1. Files Module
99 8 Bullwinkle
100 8 Bullwinkle
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).
101 8 Bullwinkle
102 8 Bullwinkle
In order to keep your Files organized, you can use Versions to mimic sub-folders. *In Settings, Create a New Version*:
103 8 Bullwinkle
104 8 Bullwinkle
!Files01.png!
105 8 Bullwinkle
106 8 Bullwinkle
107 1 Bullwinkle
108 22 Bullwinkle
.
109 22 Bullwinkle
110 8 Bullwinkle
The Version *Name* is what users will see in the Files listing as a header -- similar to a folder.
111 8 Bullwinkle
The Optional *Wiki Page* is the name of a page in your project's Wiki that is linked to this Version's Files.
112 1 Bullwinkle
113 8 Bullwinkle
!Files02.png!
114 8 Bullwinkle
115 1 Bullwinkle
116 1 Bullwinkle
117 22 Bullwinkle
.
118 22 Bullwinkle
119 8 Bullwinkle
Go to the Files Module, and click *New File* to upload a file.
120 8 Bullwinkle
121 8 Bullwinkle
!Files03.png!
122 1 Bullwinkle
123 1 Bullwinkle
124 24 Bullwinkle
125 24 Bullwinkle
.
126 24 Bullwinkle
127 24 Bullwinkle
In the *New File dialog*, use the pull-down menu to choose the Version/Folder where you want the file.
128 24 Bullwinkle
129 24 Bullwinkle
!Files04.png!
130 1 Bullwinkle
131 22 Bullwinkle
.
132 22 Bullwinkle
133 10 Bullwinkle
h1. Version Control
134 11 Bullwinkle
135 10 Bullwinkle
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:
136 1 Bullwinkle
137 26 Bullwinkle
* Automatic backup of _every_ change made by _every_ developer on the team. (Well, every _committed_ change.)
138 22 Bullwinkle
* Semi-Automatic Merge(*)
139 10 Bullwinkle
* Encourages good documentation and good communication between team members.
140 10 Bullwinkle
* Ability to mark a "version", which includes all of the source files required to make that version.
141 10 Bullwinkle
* Ability to roll back changes (in case you try something that does not work).
142 1 Bullwinkle
143 1 Bullwinkle
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).
144 22 Bullwinkle
145 22 Bullwinkle
bq. (*) 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. 
146 22 Bullwinkle
147 22 Bullwinkle
bq. 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.
148 22 Bullwinkle
149 22 Bullwinkle
bq. 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. 
150 22 Bullwinkle
151 22 Bullwinkle
bq. 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.
152 22 Bullwinkle
153 26 Bullwinkle
h2. SubVersion Most-Used Commands
154 1 Bullwinkle
155 26 Bullwinkle
*CheckOut*
156 26 Bullwinkle
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.
157 1 Bullwinkle
158 31 Bullwinkle
*SVN Update*
159 31 Bullwinkle
(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.
160 31 Bullwinkle
161 26 Bullwinkle
*SVN Commit* (CheckIn)
162 26 Bullwinkle
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.
163 26 Bullwinkle
164 26 Bullwinkle
*Merge*
165 26 Bullwinkle
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. 
166 26 Bullwinkle
167 26 Bullwinkle
.
168 26 Bullwinkle
169 32 Bullwinkle
h2. Check Out
170 26 Bullwinkle
171 32 Bullwinkle
h3. How to Get a Working Copy of a Project
172 30 Bullwinkle
173 32 Bullwinkle
174 29 Bullwinkle
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":
175 26 Bullwinkle
176 26 Bullwinkle
!SVN01.png!
177 1 Bullwinkle
178 27 Bullwinkle
.
179 1 Bullwinkle
180 27 Bullwinkle
2) In Windows Explorer, make a folder where you want to put the FLSES project tree:
181 27 Bullwinkle
182 27 Bullwinkle
!SVN02.png!
183 27 Bullwinkle
184 27 Bullwinkle
.
185 27 Bullwinkle
186 30 Bullwinkle
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.
187 30 Bullwinkle
188 30 Bullwinkle
.
189 30 Bullwinkle
190 27 Bullwinkle
3) Right-click the folder and select "SVN Checkout":
191 27 Bullwinkle
192 27 Bullwinkle
!SVN03.png!
193 27 Bullwinkle
194 27 Bullwinkle
.
195 27 Bullwinkle
196 27 Bullwinkle
4) In the Checkout dialog, enter the URL of repository: http://svn.the-starport.net/flses. Leave everything else at their default settings:
197 27 Bullwinkle
198 27 Bullwinkle
!SVN04.png!
199 27 Bullwinkle
200 27 Bullwinkle
.
201 25 Bullwinkle
202 25 Bullwinkle
5) Click "OK"
203 25 Bullwinkle
204 25 Bullwinkle
If you are prompted for username and password, use your Forge credentials.
205 1 Bullwinkle
206 30 Bullwinkle
TortoiseSVN (TSVN) should then fill your selected folder with the newest revision from the FLSES SVN Repository.
207 1 Bullwinkle
208 30 Bullwinkle
*Notes*
209 30 Bullwinkle
* 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.
210 30 Bullwinkle
* (Note that SubVersion CheckOuts are different than other Version Control Systems which lock Checked Out files.)
211 30 Bullwinkle
* You should Check Out into an empty folder (because TortoiseSVN (TSVN) will just download a copy from the server anyway).
212 1 Bullwinkle
* 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.
213 1 Bullwinkle
* 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.
214 32 Bullwinkle
215 32 Bullwinkle
h2. Troubleshooting
216 32 Bullwinkle
217 32 Bullwinkle
If you have problems using SubVersion (SVN) or the TortoiseSVN (TSVN) client, then here are some tips:
218 32 Bullwinkle
219 32 Bullwinkle
* The server is always right.
220 32 Bullwinkle
* If the server is not right, then make it right by Committing your changes. You can _Commit_ Deletes and Renames as well.
221 32 Bullwinkle
* 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_.
222 32 Bullwinkle
* If an _Update_ fails, repeat until it finishes without error.
223 32 Bullwinkle
* _Clean Up_ looks for errors in your Working Copy and resolves them automagically.
224 32 Bullwinkle
* 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.
225 25 Bullwinkle
226 22 Bullwinkle
227 25 Bullwinkle
.
228 22 Bullwinkle
229 25 Bullwinkle
.
230 22 Bullwinkle
231 23 Bullwinkle
.
232 25 Bullwinkle
233 25 Bullwinkle
.
234 25 Bullwinkle
235 25 Bullwinkle
.
236 23 Bullwinkle
237 23 Bullwinkle
bq. Last edited by *Bullwinkle* 2010-05-11
238 22 Bullwinkle
239 25 Bullwinkle
.
240 22 Bullwinkle
241 25 Bullwinkle
.
242 22 Bullwinkle
243 22 Bullwinkle
.
244 1 Bullwinkle
.