List of All Best Practices

1. Best Practices for Editing Files in Localization Perspective
   • Always edit available SITE- and USER-level files only in the Localization Perspective.
   • Creating vs. Importing
     • If your site desires a new Smart Tool, Procedure, Utility, Smart Init, or Text Formatter, then look on the NWS SCP for the type of file that will do what your site desires. If there is a file on the NWS SCP that your site desires, then use the Subversion checkout out command to download the file (or files in the case of a Text Formatter). If the file (or files in the case of a Text Formatter) you downloaded is not a Smart Init, then copy the file (or each file in the case of a Text Formatter) to a .py file with the same name. For non-Text Formatter files, go into the Localization Perspective and right-click on the folder of the type of file you downloaded and click Import File... . Then navigate to your file and left-click okay. For Text Formatter files, go into the Localization Perspective and for each previously named .TextProduct file (i.e., TTT, TTT_RR, TTT_XXX, where TTT is the three letter product name, XXX is wfo/site id, and RR might be the specific region or might just be RR) right-click on the Text Products Folder and click Import File... . Then navigate to your file and left-click okay. Next for each previously named .TextUtility file (i.e., TTT_Overrides, TTT_RR_Overrides, where TTT is the three letter product name, and RR might be the specific region or might just be RR) right-click on the Text Utilities Folder and click Import File... . Then navigate to your file and left-click okay. Next for each previously named .template file (i.e. TTT_SiteOverrides, TTT_SiteDefinition, where TTT is the three letter product name) right-click on the Text Utilities Folder and click Import File... . Then navigate to your file and left-click okay. The SiteOverrides and SiteDefinition files will have to be edited before the Text Formatter will be able to be used.
     • When there is not an existing Smart Tool, Procedure, Utility, Smart Init, or Text Formatter on the NWS SCP that your site desires to carry out a certain purpose, then you can create one from scratch for non-Text Formatters by clicking on the folder of the type of file your site desires and left click New... . For Text Formatters you will click on the Text Product Folder and left click New... and if desired you can create Text Utilities for the Text Formatter too in a similar manner.
     • Whenever possible import files as opposed to creating your own from scratch.
   • Whenever you make changes to GFE files, they should be backed up to VLab using subversion (svn).
2. How to set up and use <backuser>
   • Edit the SITE-level scvbu.properties file by setting SVCBU_USER equal to 1 and SVCBU_USER_ID equal to backuser.
   • Save these changes and then open GFE and Deactivate and Reactivate your site using the Site Activation GUI under the GFE Menu.
   • Open a terminal window on an AWIPS workstation.
   • Type ps -efw | grep "alertviz -p".
     • Write down the number after -p for your username.
   • Type xhost +SI:localuser:backuser
     • The response from the terminal should be: localuser:backuser being added to access control list
   • Type sudo -u backuser /awips2/cave/cave.sh
     • If you get a permission denied error, then only the ITO and ESA can run this command. You will need to ask one of them to run it for you.
   • When CAVE starts up, the Connectivity Preferences window will popup.
     • Enter your site id (XXX) in the Site Box.
     • Enter the port number you wrote down in the Alert Server box at the end of the line in the box after the colon.
     • Validate and left-click OK.
   • Open the Localization Perspective and it should be running as the <backuser> account.
   • You can now edit any <backuser> file.
   • You can copy any SITE- and/or CONFIGURED-level file to <backuser> to make changes to them for the <backuser> account.
3. Documentation
   • Comments
     • Use comments to document your code and any changes made to existing code.
     • Every Python and XML file should have a comment at the beginning of the file describing what the file does and/or is used for.
     • Important Python methods/functions should have a comment explaining what the method/function does.
   • Change logs
     • Create and update change logs to document all changes that are made to BASE-level files and for files that are a part of applications developed locally.
     • Also create and update change logs to document changes that are made to every Python and XML file.
4. Annual Clean-up of SITE-level Files
   • New data sets and regional changes should be incorporated when available and at least once a year.
   • Frequently and at least once a year, ensure no specific user has unneeded files or files that may prevent them from using required SITE-level configuration settings.
   • Frequently and at least once a year, remove duplicate or obsolete entries from configuration files, including localConfig and your SITE-level gfeConfig.
   • At least once a year, remove duplicate or obsolete entries from Smart Tools, Procedures, Text Products, Text Utilities, Utilities, and Smart Init files.
   • At least once a year perform a cleanup of SITE-level edit area files, the SITE-level gfeLevelMappingFile.xml file, the SITE-level gfeParamInfo.xml file, the SITE-level gfeParamName.xml file, SITE-level Parameter Info Files, and the SITE-level iscSendSampleDef file.
     • For all of the files listed above cleanup consists of removing duplicate or obsolete entries.
     • Edit areas need to be cleaned up due to the addition of new shapefiles like zone changes or CWA swaps.
   • If backup pairings change, then localVTECPartners.py will need to be cleaned up.
   • At least once a year remove obsolete or unnecessary files from the GFE and GFE Server directories in the Localization Perspective.
5. Make Backups
   • Prior to making changes to any file in the Localization Perspective, make a backup copy. The backup copy should be saved somewhere so it isn't visible in the Localization Perspective.
6. Old Files on the Server-side (and CAVE-side)
   • Prior to removing any files from the Localization Perspective, copy them to a backup directory with an appended date in the filename. These files should not be visible in the Localization Perspective. This is especially important for Server-side files as having lots of old Server-side files can affect GFE start-up.
7. GFE Restarting
   • After overriding/changing a GFE configuration or utilities file, you will need to restart GFE/CAVE.
8. GFE Server Restarting
   • After overriding/changing a GFE server configuration file, you will need to restart the GFE server.
   • Prior to restarting the GFE server, let your office know and kick everyone out of GFE.
   • When GFE is back up, let your office know.
   • Find a good time at your office when this will cause the least amount of inconvenience.
9. Have GFE in its own CAVE
   • Whenever you are working in GFE, have it in its own CAVE.
10. Python
    • When writing new code, break the code up into smaller pieces.
    • Use comments to document your code and any changes made to existing code.
    • Add new code and make modifications to existing code incrementally and then test.
    • When writing code, use logical naming conventions so that other members of your office will be able to understand what the code does.
    • When troubleshooting code, use print statements.
      • In Python 3 be sure to use parentheses around what you want to print (e.g., print ("hi"))
    • When importing numpy, use import numpy as np.
      • Use np.method (i.e., np.min, np.where, etc.,) to call the various numpy methods.
11. Practice Database
    • Whenever possible if you are going to be making changes to the database, use practice mode and the practice database first. If everything works in practice mode after making the database changes, then you can make the changes in operational mode and to the official/forecast database.
12. Testing Under USER-level
    • Whenever making changes to a SITE-level file, copy the file to USER-level first and then make the changes. Next, test the changes and if everything works properly, then you can copy the changes into the SITE-level file.
      • This is especially important when updating Text Formatters.
13. ISC
    • The extraISCparms and REQUESTED_ISC_PARMS lists MUST be overridden/added to use plus equals (+=) and NOT equals (=).