Freelancer Community Network

ForgeTips » History » Version 37

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