Freelancer Community Network

ForgeTips » History » Version 34

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