PAMMS File Naming Requirements & Best Practices

A file’s name is used to create its page URL. Changing a file’s name will break links, cross-references (xrefs) in other files, and incoming links to the page from external websites.

When a file name is changed all cross-references (xrefs) links in all other policy files would need to be updated to the new name. This is why it is important that the file name be correct when initially created.

FILE NAME REQUIREMENTS:

Most attachments that are documents are presented to the visitor as PDF documents. However, these attachments are not necessarily stored in the content repositories in the PDF format. This section explains what format to choose and how an attachment that is automatically converted to PDF should be referenced.

Whenever possible, the files stored (i.e., committed) to a content repository, including attachments, should be kept in its source format. (The source format is the format authors use to edit the file.) That means that if the file is available in .docx format (a Microsoft Word document), then it should be saved (and referenced) as a .docx file, not a .pdf file. See gitlab.com/gadhs/pamms-sources/das-aps/-/tree/main/modules/aps-5500-manual/attachments/appendix-g for examples. (If you store the .docx file in the content source repository, do not also store the .pdf file.)

When Antora builds the site, it uses Microsoft Office to automatically convert all .docx files to .pdf files. (Currently, .xlsx files are not converted to .pdf.)

Even though the .docx files are converted to .pdf files, you should still reference the file using its source format. That means that that xref to the attachment should end in .docx, not .pdf. Antora automatically rewrites the .docx reference so it points to the .pdf file in the site.

You should not store .doc files (the old Microsoft Word format) in the content repository. Always save the file as .docx before committing it.

One exception to the rule of storing attachments in their source format is memorandums and letters that are read-only and thus not intended to be modified. In this case, relying on the automatic conversion from .docx to .pdf adds unnecessary overhead. It also invites authors to modify them despite the fact that they are not meant to be modified. For these documents, they should be stored in the content repository as .pdf. An example is an MT letter.

Another exception are forms with signature fields. To our knowledge, signature fields have to be added to a .pdf using Adobe Reader. Therefore, they must be stored in .pdf format to preserve this modification.

For all new issues the title should start with the Program Initials and then the update reason or cause.

The Merge Request and Branch will keep the title from the Issue should add the word resolves in front of it.

GitLab Issues Naming Convention Examples:

GitLab Merge Request Naming Convention Examples: