Standards and Policies

Software Standards

The links in this chapter point to standards, guidelines, and best practices that developers are expected to follow when creating or modifying source code in the LSST Stack. All source code (and ancillary files, such as configuration files) are subject to peer review prior to being integrated with the Stack, and adherence to these software standards will be one component of the review. 

Coding

• DM Coding Style Policy:: defines the strictness of compliance specified for DM programming languages' individual rules.
  • Editor configurations enforcing LSST coding standards
    • Lisp for Emacs
    • Config for VIM

• C++ Coding Standard
  • C++ Coding Standards Compliance
  • C++ Policies
    
    • Policy on use of C++11/14 language features
    • How to use C++ templates 
    • OnUsingUsing:: C++'s Using Statement Convention (still relevant?)
      
      
• Python Coding Standard

  • Python Coding Standards Compliance

  
  
• Database and Terminology

• • Baseline Database Schema (trac, current)

  • Naming Conventions Used in the Schema (trac, current)
    

  • Policy on Updating Released Datasets

• Documentation-Standards for C++ and Python
  • Policy on updating Doxygen documentation directly on the git Master Branch

Testing 

• Software Unit Test Policy
  • Documentation for the Python unittest unit testing framework.
• Coverage Analysis 
• Source code profiling

Licensing

• LSST Copyright and Licensing Notices :: DM source code is distributed under the GPL-3 license. Developers must insert the copyright header at the beginning of all source files. 
  • Copyright header templates for various languages are available. 
  • The official licensing text is at :: https://www.lsstcorp.org/LegalNotices/LsstSourceCopyrightNotice.txt.
• DM Acknowledgements of Use for work done outside the LSST Team. 
• Policy on Wiki Use for  DM documentation
  

Best Practices

The following is a collection of best-practices that should be followed for DM code development. 

• Git commits
• Transferring Code Between Packages
• Documentation Guidelines discusses levels of documentation and the information required in each level.
• Changing Task defaults.

  • Occasionally it is necessary to change the defaults in the config for a particular task.  This can lead to inconsistencies in the documentation.  Developers who change defaults in the config should take it upon themselves to change documentation where it exists to reflect the same behavior as when the documentation was written.  For example, if a default is changed from False to True, documentation should be updated to specify False for that config attribute using the --config argument.  If the documentation references a specific version of the code, no changes should be made since the operation of that version will remain unchanged by the newer defaults.  At the very least, both Confluence and community.lsst.org should be searched.

• DM/Policy/ls.st ::  using the URL shortener

Process and Workflow

• DM software management and engineering process :: LSE-17 Systems Engineering Management Plan, Appendix 4.1
• Discussion and Decision Making Process

• Clarifying DM Process Terminology   (trac - needs some update)

Needs Major Revision or Obsolete

The following Trac documents are probably obviated or obsolete. 

• Process
  • LsstDCTicketWorkflow :: Ticket Workflow Process - TO BE TOTALLY REVISED
  • DM Branching Policy  - TO BE TOTALLY REVISED
    
  • CodeReviewProcess :: Code Modification Policy: Using Trac to Track Code Reviews – TO BE  UPDATED
    
  • OnVersionNumbers :: Release version numbering conventions - TO BE MOVED & UPDATED
  • ReleasingNewProductVersions :: Creating and obtaining new releases - TO BE MOVED & TOTALLY REVISED
  • Policy on Changing a Baseline Requirement :: process for altering CCB-baselined  DM Requirements - Replaced by RFC Process with TCT exception
    

• DM/Policy/UsingDMCode/FAQ – relevant but not here...move to near the code stack usage doco.

• ServerBackupPolicy -  (asked lsst-admin for new content)