WIP: major reorganization.

lsst-ts · Oct 17, 2023 · 1bb0d3f · 1bb0d3f
1 parent c5e91b6
commit 1bb0d3f
Show file tree

Hide file tree

Showing 24 changed files with 121 additions and 142 deletions.
diff --git a/...idelines/conda/Jenkinsfile.conda.template → ...idelines/conda/Jenkinsfile.conda.template b/...idelines/conda/Jenkinsfile.conda.template → ...idelines/conda/Jenkinsfile.conda.template
diff --git a/doc/guidelines/conda/index.rst → doc/development-guidelines/conda/index.rst b/doc/guidelines/conda/index.rst → doc/development-guidelines/conda/index.rst
diff --git a/doc/guidelines/conda/meta.yaml.template → ...pment-guidelines/conda/meta.yaml.template b/doc/guidelines/conda/meta.yaml.template → ...pment-guidelines/conda/meta.yaml.template
diff --git a/doc/development-guidelines/creating-new-repository.rst b/doc/development-guidelines/creating-new-repository.rst
@@ -0,0 +1,52 @@
+
+.. _creating_a_new_repository:
+
+#########################
+Creating a New Repository
+#########################
+
+The simplest way to create a new repository is to use sqrbot-jr on slack.
+Upon request, the bot can create new repositories in the lsstts GitHub organization with the standard template, for a given type of product.
+
+To do this, open the slack desktop or web app.
+Go to the bottom of the left hand panel and find the "App" section.
+Click on the "+" sign, search for sqrbot-jr and start a chat with it.
+Send a message with "create project" to the bot and slack and follow the prompts to have the repository automatically created and setup for you.
+
+.. image:: /images/sqrbot-jr-1.png
+
+Then pick the template ``LSST EUPs Package``
+
+.. image:: /images/sqrbot-jr-2.png
+
+Fill out the following fields:
+
+name
+  The name of the package in the form of ``ts_{csc_name}``
+
+Github Organization
+  Choose ``lsst-ts``
+
+Copyright
+  Choose ``AURA``
+
+Flavor
+  Choose ``DDS Python``
+
+.. image:: /images/sqrbot-jr-3.png
+
+Alternatively, you can also use the `template kit tool <https://github.com/lsst/templates>`_ provided by DM.
+Once you have created the repository with its initial commit (either with sqrbot-jr or manually with the template kit), you need to set it up to follow our :ref:`workflow <development-workflow>`.
+
+- First you need to create a ``develop`` branch from ``main`` and push it to the repository.
+- Open the repository in GitHub and select the "Settings" tab at the top.
+- Go to "Branches"
+- On the "Default branch", click on "switch to another branch" and select develop instead of main.
+- On "Branch protection rules", click on "Add rule".
+- On "Branch name pattern" type "develop".
+- On "Protect matching branches" select;
+
+  - Require pull request reviews before merging
+  - Include administrators
+
+- At the bottom of the page select "Create"
diff --git a/doc/guidelines/language/index.rst → ...development-guidelines/language/index.rst b/doc/guidelines/language/index.rst → ...development-guidelines/language/index.rst
diff --git a/...uidelines/language/pyproject.toml.example → ...uidelines/language/pyproject.toml.example b/...uidelines/language/pyproject.toml.example → ...uidelines/language/pyproject.toml.example
diff --git a/doc/guidelines/language/python.rst → ...evelopment-guidelines/language/python.rst b/doc/guidelines/language/python.rst → ...evelopment-guidelines/language/python.rst
@@ -34,17 +34,4 @@ The team uses the following tools to enforce the style guide.
 :mypy: Performs type checking on the code (optional).
 
 There are several other optional style guide tools as well.
-This is enforced by a tool called ``pre-commit``, see the reference below.
-
-Additional Information
-======================
-
-*  See :ref:`Jenkinsfile` for information on how to setup the CI job for your packages.
-   This job is usually used to test PRs and are triggered by pushes to the github repo.
-*  See :ref:`Conda` for information on how to setup the CI conda job for your packages.
-   This job is used to build conda packages.
-   They are triggered daily by the build system and automatically when tags are pushed to the github repo.
-*  See :ref:`documentation-guide` for information on how to write and publish package documentation.
-*  See :ref:`Versioning` for information on how to version your packages.
-*  See :ref:`reporting-xml-release-work` for information on how to update CSCs interfaces.
-* See :ref:`pre-commit` for more information on the pre-commit tool.
+This is enforced by a tool called :ref:`pre-commit`.
diff --git a/doc/guidelines/language/setup.py.example → ...ment-guidelines/language/setup.py.example b/doc/guidelines/language/setup.py.example → ...ment-guidelines/language/setup.py.example
diff --git a/doc/procedures/pre_commit.rst → doc/development-guidelines/pre_commit.rst b/doc/procedures/pre_commit.rst → doc/development-guidelines/pre_commit.rst
diff --git a/doc/procedures/csc_xml_addition_removal.rst → ...idelines/xml/csc_xml_addition_removal.rst b/doc/procedures/csc_xml_addition_removal.rst → ...idelines/xml/csc_xml_addition_removal.rst
@@ -1,3 +1,6 @@
+
+.. _adding_or_removing_a_csc_from_the_xml_interface:
+
 ###############################################
 Adding or Removing a CSC from the XML Interface
 ###############################################

diff --git a/...procedures/reporting-xml-release-work.rst → ...elines/xml/reporting-xml-release-work.rst b/...procedures/reporting-xml-release-work.rst → ...elines/xml/reporting-xml-release-work.rst
diff --git a/doc/procedures/xml_changelog.rst → ...elopment-guidelines/xml/xml_changelog.rst b/doc/procedures/xml_changelog.rst → ...elopment-guidelines/xml/xml_changelog.rst
diff --git a/doc/guidelines/development/components.rst b/doc/guidelines/development/components.rst
@@ -30,55 +30,6 @@ Component Resources
 
 * A template has been produced for the format above which every application should follow.
 
-Creating a New Repository
--------------------------
-
-The simplest way to create a new repository is to use sqrbot-jr on slack.
-Upon request, the bot can create new repositories in the lsstts GitHub organization with the standard template, for a given type of product.
-
-To do this, open the slack desktop or web app.
-Go to the bottom of the left hand panel and find the "App" section.
-Click on the "+" sign, search for sqrbot-jr and start a chat with it.
-Send a message with "create project" to the bot and slack and follow the prompts to have the repository automatically created and setup for you.
-
-.. image:: /images/sqrbot-jr-1.png
-
-Then pick the template ``LSST EUPs Package``
-
-.. image:: /images/sqrbot-jr-2.png
-
-Fill out the following fields:
-
-name
-  The name of the package in the form of ``ts_{csc_name}``
-
-Github Organization
-  Choose ``lsst-ts``
-
-Copyright
-  Choose ``AURA``
-
-Flavor
-  Choose ``DDS Python``
-
-.. image:: /images/sqrbot-jr-3.png
-
-Alternatively, you can also use the `template kit tool <https://github.com/lsst/templates>`_ provided by DM.
-Once you have created the repository with its initial commit (either with sqrbot-jr or manually with the template kit), you need to set it up to follow our :ref:`workflow <development-workflow>`.
-
-- First you need to create a ``develop`` branch from ``main`` and push it to the repository.
-- Open the repository in GitHub and select the "Settings" tab at the top.
-- Go to "Branches"
-- On the "Default branch", click on "switch to another branch" and select develop instead of main.
-- On "Branch protection rules", click on "Add rule".
-- On "Branch name pattern" type "develop".
-- On "Protect matching branches" select;
-
-  - Require pull request reviews before merging
-  - Include administrators
-
-- At the bottom of the page select "Create"
-
 Component Roles
 ===============
 

diff --git a/doc/guidelines/development/docker/docker.rst b/doc/guidelines/development/docker/docker.rst
@@ -1,12 +1,8 @@
-##################
-Docker Development
-##################
-
-Docker is TSSW's preferred method for CSC development.
-Docker is a containerization software designed to help application environments maintain consistency between machines.
+.. _installing_docker_on_centos:
 
+###########################
 Installing docker on CentOS
-===========================
+###########################
 
 Docker Install via Docker's repository
 --------------------------------------

diff --git a/doc/guidelines/development/index.rst b/doc/guidelines/development/index.rst
diff --git a/doc/guidelines/index.rst b/doc/guidelines/index.rst
diff --git a/doc/images/IMG_4884 2.jpg b/doc/images/IMG_4884 2.jpg
diff --git a/doc/images/IMG_4885.jpg b/doc/images/IMG_4885.jpg
diff --git a/doc/index.rst b/doc/index.rst
@@ -3,38 +3,63 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-######################################################
-Telescope and Site Software: Procedures and Guidelines
-######################################################
+###########################################
+Telescope and Site Software Developer Guide
+###########################################
 
 This page contains general procedures and guidelines adopted by the Telescope and Site Software (TSSW) team.
 It serves as reference for the work done during construction, and future operations, of the Vera Rubin Observatory control software.
 
 
-Procedures
-##########
-This section outlines procedures that our team uses such as workflow, jira and sprint management.
+.. Procedures
+.. ##########
 
-Contains information about the team organization and overall workflows.
-This is a good starting point for new contributors to understand how to cooperate with the software team.
+.. This section outlines procedures that our team uses such as workflow, jira and sprint management.
 
+.. Contains information about the team organization and overall workflows.
+.. This is a good starting point for new contributors to understand how to cooperate with the software team.
 
-.. toctree::
-  :glob:
-  :maxdepth: 3
+Team
+####
 
-  procedures/index
+Basic information about the TSSW team and our culture.
 
+- :ref:`onboarding_checklist`
+- :ref:`culture_and_standards`
 
-Guides
-######
-This section contains guides for docker, development and languages that our team uses.
-Contains general guidelines for developing and contributing to the observatory control system.
+Communications
+##############
 
-.. toctree::
-  :glob:
-  :maxdepth: 3
+TSSW adopts the same communications channels and procedures as Data Management (DM).
+For more information see `DM Communications`_ Guidelines.
 
-  guidelines/index
+.. _DM Communications: https://developer.lsst.io/#part-communications
 
+Work Management
+###############
 
+How work is coordinated and executed by TSSW.
+
+- :ref:`Jira_Workflow`
+- :ref:`development_workflow`
+
+Development Guides
+##################
+
+For the most part TSSW follow `DM code style guidelines`_.
+We highly recommend reviewing these guidelines before contributing to TSSW repositories.
+
+.. _DM code style guidelines: https://developer.lsst.io/coding/intro.html
+
+Following are a few guidelines particular to TSSW software:
+
+- :ref:`creating_a_new_repository`.
+- :ref:`Python` is the language used most broadly by TSSW.
+- :ref:`pre-commit` is a tool used to help guarantee style, formatting, etc consistency across the project.
+- :ref:`Conda` is the official package management system used to distribute TSSW software.
+- :ref:`Jenkinsfile` contains information on how to setup the CI job for your packages.
+- :ref:`documentation-guide` contains information on how to write and publish package documentation.
+- :ref:`Versioning` describes how to version your packages.
+- :ref:`reporting-xml-release-work` describes how to update CSCs interfaces.
+- :ref:`adding_or_removing_a_csc_from_the_xml_interface` describes how to add new components to the observatory control system.
+- :ref:`XML-version-history` describes how to handle versioning of the control system interfaces.
diff --git a/doc/procedures/culture-and-standards.rst b/doc/procedures/culture-and-standards.rst
@@ -0,0 +1,6 @@
+
+.. _culture_and_standards:
+
+##################################
+Team culture and conduct standards
+##################################
diff --git a/doc/procedures/index.rst b/doc/procedures/index.rst
diff --git a/doc/procedures/onboarding-checklist.rst b/doc/procedures/onboarding-checklist.rst
@@ -0,0 +1,8 @@
+
+.. _onboarding_checklist:
+
+####################
+Onboarding checklist
+####################
+
+TBD
diff --git a/doc/procedures/development_workflow.rst → doc/work_management/development_workflow.rst b/doc/procedures/development_workflow.rst → doc/work_management/development_workflow.rst
@@ -1,4 +1,4 @@
-.. _development-workflow:
+.. _development_workflow:
 
 ####################
 Development Workflow

diff --git a/doc/procedures/jira.rst → doc/work_management/jira.rst b/doc/procedures/jira.rst → doc/work_management/jira.rst
@@ -1,3 +1,5 @@
+.. _Jira_Workflow:
+
 #############
 Jira Workflow
 #############