File-Naming Best Practices (Discussion)

[The Freezer]

Introduction:

This guide is an introduction to the file naming conventions you will see used when using ssTek. As the already well-established release groups had long ago discovered, a filename can contain a ton of info. So it's important how we structure or format our database-like filenames.

Indexing Structures, Filing Systems, and Character Sets:

With any large amount of information, it is important for the people accessing it to have some kind of structure to navigate their way to the information they're looking for. If there is no structure for locating specific data, the collection of information is virtually useless and the task of finding what you are looking for becomes like trying to find a needle in a haystack.

For this reason, a relatively new convention was developed for the naming of files. This naming convention was formally ratified by many - if not most - of the well known release groups. The use of these standards, along with the files they are attached to, have trickled down to the P2P community, and now to us here at ssTek.

Rules for naming files and folders are an important part of the standards. Correctly named folders make it easier to maintain clean archives and unique filenames are necessary to allow any duplicate checker program to work properly.

Also, since FTP servers, operating systems, or file systems may not allow special characters in file or directory names, only a small set of characters is allowed. And substitutions are made where special characters would normally be used (e.g. ç replaced by c); or these characters are simply omitted, such as an asterisk(*).

So in order to minimize the problems due to the many platforms a release may encounter during its distribution, a very specifically defined character set is used in naming of the files and folders. This ubiquitous character set includes the upper- and lower-case English alphabet, numerals, and several basic punctuation marks. It is outlined below:

[font=Courier New]ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789'!+-,._()[][/font]

The Absence of Spaces:

Since spaces are explicitly disallowed in all current standards, the first thing you'll see is a lot of dots; or full stops if you insist on using the 20th century term for them. Get used to it and learn to love 'em.

The reason you see dots instead of spaces (Kind.Of.Like.This) is because different operating systems and software read spaces in different ways. For example, even in simple HTML, a space can often be automatically converted to %20, depending on why kind of software you're using to read it and how well that software converts the encoded text into human-readable text.

Rather than making people decipher file%20names%20like%20this%20which%20are%20hard%20to%20read, the dots make file.names.like.this.much.easier.to.read.

Spaces in file names can also cause broken links, because word processing tools like Microsoft Word, and e-mail clients like Microsoft Outlook, recognize spaces as an opportunity to move to another line. Therefore, a link to

\\Ah1\Intranet\ar\naming conventions

could become

\\Ah1\Intranet\ar\naming
conventions

Another difference that is found among operating systems and software is the acceptable length of file names. Some systems allow up to 256 characters, while others allow far fewer.

And finally many scripts/batch/cmd files would require filenames with spaces to be enclosed in double-quotes otherwise the spaces are interpreted as parameter breaks much like what the word processing tools would do to them.

Tagging Convention:

First the syntax. (NOTE: The following should be considered all one file or folder name):

[font=Courier New][<Developer>.]<Title>_v<Version>|c<Year>[_<Language>][_<OS>][_<Architecture>]
_<BuildType>[_<Category>|<Additional>][_<Releaser>][/font]

Yes, this does look very cryptic and daunting but fear not, that's what you have this guide for. A couple things you should know about the syntax are follows:

• Anything inside brackets "[]" is optional
• Do not actually enter the "<>" characters
• "|" represent choices

Here, we'll try to walk you through some of the most important parts of our file-naming standard:

1. NO spaces.
   
2. Substitute dots(.) for spaces inside <field>s.
   
3. Use underscores(_) as separators between <field>s.
   
4. NO double-dots nor double-underscores.
   
5. <Developer> is only really mandatory if the application name is not unique enough that duplicates are not likely to exist. This means that you must include the developer in the case where checks for duplicates for your application name will also return results that do not match the application you are releasing. Including the developer would also be appropriate if the developer's releases are typically listed together, those from Adobe or Microsoft for example.
   
6. <Title> must be the "official" name of the application. Do not omit dashes, think of your duplicate checking results. This is the name in the about box or splashscreen of the application, or if this is not available, the name listed on the website.
   
7. _v<Version> should be used for applications, and _c<Year> should be used for games. Dashes are also appropriate here. E.g, "-Beta"
   
8. The <Language> tag must be used only on NON English releases. Multilingual and bilingual are optional.
   
9. It is recommended to omit the <OS> tag when it is "All Windows" (= NT5 & NT6 based windows, always with latest official service pack). Currently valid OS tags are:
   • NT5 [2K/XP/2K3]
   • NT6 [Vista/7]
   • Linux
10. It is recommended to omit the <Architecture> tag when it is x86 and it works perfectly okay on an x64 system or if separate installers are included for the two different architectures but only one will get installed depending on the target system. Currently valid Architecture tags are:
    • x86 [will ONLY run correctly on x86 systems]
    • x64 [will ONLY run on x64 systems]
    • DualArch [will run on either x86 or x64 systems... this ONLY works with ppApps or ppGames exclusively]
11. <BuildType> is the type of deployment package/build. Possible tags are:
    
    • ssApp
    • ppApp
    • ppGame
12. Releasers should use some common sense to keep the filename a reasonable length.

Examples:

Finally, to help illustrate some of the rules, we present a few examples of properly formatted filenames should look like:

[font=Courier New]7-Zip_v9.25Beta_x64_ssApp_bphlpt.apz
Bulk.Rename.Utility_v2.7.1.1_ppApp.apz
CCleaner_v2.36.1233_ppApp.apz
Elaborate.Bytes.Virtual.CloneDrive_v5.4.4.0_ssApp.apz
HashCheck.Shell.Extension_v2.1.11.1_ssApp_Addon.apz
Ben.There,Dan.That!_c2008_ppGame_Adventure_TheFreezerBox.pgz[/font]

[The Freezer]

Wow, haven't visited this thread in a while. Which is probably a good thing; means that the file-naming "standard" seems to be working and didn't need revised... till now.

Briefly, and to put it simply, Trouba has come up with another scheme for "DualArch" ppApps.

First let's have a quick lesson to bring everyone onto the same page. There are basically two ways of handling the OSArch issue(s):

Type 1
SingleArch-Installer --> SingleArch-Installed. It is the most primitive but effective way of deploying apps. It only requires the release-package to designate the target OSArch in the .app-file (under <Architecture>). It is also going to have the smallest-sized deployment packages. But to be complete, one will need to create two such packages: one for x86 (32-bit) and another for x64 (64-bit). They'll also have separate but different file-names for each package, as discussed in this thread already (see first post -- bullet point 10).

Type 2

1. DualArch-Installer --> SingleArch-Installed. It is the scheme used almost exclusively with ssApps -- because their original installers were designed to install this way. We say almost exclusively because until now this was only used by ssApps -- this is the scheme Trouba has devised to work with ppApps as well.
   
2. DualArch-Installer --> DualArch-Installed. It is a scheme only used by ppApps -- because only ppApps can utilize it. Period. End of discussion.

Okay, as it stands now, this creates a bit of a problem for someone looking at a DualArch ppApp. Is it a Type 2a or 2b? Previously, the assumption could be made that if it's an ssApp it's Type 2a and if it's a ppApp then it's Type 2b.

So a decision needs to be made on how to designate the two kinds of Type 2's we could have and how to start naming the resulting deployment packages.

There's no question that ssApp packages were on the scene first (so to speak) and they are in fact the more traditional-behaving unattended installing technique; whereas, ppApps are a more extreme and unique method of deployment that they are also an exclusive design of ssTek tools.

Looking at it thus, it becomes obvious -- to me at least -- that the Type 2a DualArch used by ssApps (and now ppApps) should therefore be the default when "Any" is selected under <Architecture>. It will also require no extra filename tag since this is the naming scheme ssApp packages have been utilizing for quite some time already. (Note: there was a tag for these, "_x86-x64", but it was rarely used if at all.)

Type 2b is a universal DualArch but will now need a special tag added to the filename in order to distinguish this particular type of DualArch ppApp from it's Type 2a brother. To me, it's this type that truly deserves to be called "DualArch" because it IS a true Dual Architecture -- and in every sense of the definition, IMO.

The task is now two-fold; we need to amend the .app-file spec slightly to indicate a DualArch capacity for ppApps under the <Architecture> and update SetupS/ssEditor to implement the new ways of handling the different OSArch Types. Also, we need to amend our file-name scheme to adding a "_DualArch" tag for Type 2b ppApps.

So expect some revisions to the SetupS project here shortly

[glow=red]EDIT:[/glow]

So expect some revisions to the SetupS project here shortly

-- Done from v8.12.9.0 (September 26, 2012) RC9 onwards. See New "DualArch-Installer" forms.