Template for PRACTICES.md

PRACTICES-template.md

@@ -1,36 +1,53 @@
 # Software Development Practices
 
-This document could potentially go into the repo itself, possibly within the `.github` folder. Its purpose is to document *current* practices of the development team. By having it version controlled the practices can change over time.
+This document could potentially go into the repo itself, possibly within the `.github` folder. Its purpose is to document *current* practices of the project and development team. By having it under version control, these practices can change over time.
 
-The following is loosely in a yaml format: each top-level bullet containins a sub-list of key-value items. This is just a starter list, items and categories should be added or removed to suit each individual project. Reviewing and updating the list can be an excellent on-boarding activity.
+The following is in markdown format: categories are shown as 2nd level headings, details are lists of key-value-style pairs. This is just a starter list, items and categories should be added or removed to suit each individual project. Reviewing and updating the list can be an excellent on-boarding activity. Many of these items would be a great topic for a PSIP PTC.
 
-Any one of these categories could be a great topic for a PSIP PTC.
+## High-Level Policies
 
-- Policies
-  - location:
-  - decision making process:
-- Version Tracking Practices
+*This category contains high-level project information.*
+
+  - PI: <lead for the project>
+  - Maintainers contact: <preferred way to get in touch with maintainers>
+  - Issue Reporting: <preferred way to report issues>
+  - Decision making process: <details on how decisions are made>
+  - Code of conduct: <loction or details for code-of-conduct>
+  - Contributing guide: <location>
+
+## Coding Practices
+
+*This category contains policy information around the code itself, including documentation. The information here is relevant for all contributors.*
+
+Version Tracking Practices
   - Official source location:
-  - Source management system:
-  - Release management:
-  - Workflow:
-- Documentation Practices
-  - Website:
+  - Source management system: [ git | bazar | mercurial ]
+  - Release management: <versioning details, schedule>
+  - Workflow: [ gitflow | other | see CONTRIBUTING.md ]
+  - Branch naming policy:
+
+Documentation Practices
+  - Website: 
   - User documentation:
   - Developer documentation:
-  - Documentation expectations:
-- Testing Practices:
+  - Documentation expectations: [ documentation update with each PR ]
+
+Testing Practices
   - Unit testing:
   - Continuous integration:
-- Style Practices:
-  - Style enforcement:
-  - Style policy:
-- Issue Policies: 
-  - Bug reporting system:
-  - Issue tracking system:
-- Communication Practices:
-  - Responsiveness expectations:
+
+Style Practices
+  - Style policy: <file location>
+  - Style enforcement: <by CI on PRs>
+
+## Development Team Practices
+
+*This category is for the policies for core development team members. It includes expectations around communication and development.*
+
+Communication Practices
   - Platforms:
-- Citation Practicies:
-  - Official citation:
-  - Authorship contributions:
+  - Responsiveness expectations:
+
+Development Practices
+  - Task assignment:
+  - Task tracking: