WIP: major reorganization.

lsst-ts · Oct 18, 2023 · 64b24d2 · 64b24d2
1 parent c5e91b6
commit 64b24d2
Show file tree

Hide file tree

Showing 48 changed files with 206 additions and 167 deletions.
diff --git a/doc/guidelines/development/building.rst → doc/development-guidelines/building.rst b/doc/guidelines/development/building.rst → doc/development-guidelines/building.rst
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/procedures/contributing.rst → doc/development-guidelines/contributing.rst b/doc/procedures/contributing.rst → doc/development-guidelines/contributing.rst
diff --git a/doc/guidelines/documentation-guide.rst → ...opment-guidelines/documentation-guide.rst b/doc/guidelines/documentation-guide.rst → ...opment-guidelines/documentation-guide.rst
diff --git a/doc/development-guidelines/index.rst b/doc/development-guidelines/index.rst
@@ -0,0 +1,14 @@
+
+######################
+Development guidelines
+######################
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    language/index
+    xml/index
+    conda/index
+    tools/index
+    *
diff --git a/doc/development-guidelines/language/cpp.rst b/doc/development-guidelines/language/cpp.rst
@@ -0,0 +1,6 @@
+
+##############
+C++ guidelines
+##############
+
+TBD.
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/doc/development-guidelines/language/javascript.rst b/doc/development-guidelines/language/javascript.rst
@@ -0,0 +1,6 @@
+
+#####################
+Javascript guidelines
+#####################
+
+TBD
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/software.rst → ...ment-guidelines/software-installation.rst b/doc/procedures/software.rst → ...ment-guidelines/software-installation.rst
diff --git a/...uidelines/development/Jenkinsfile.example → ...ment-guidelines/tools/Jenkinsfile.example b/...uidelines/development/Jenkinsfile.example → ...ment-guidelines/tools/Jenkinsfile.example
diff --git a/...idelines/development/Jenkinsfile.example2 → ...ent-guidelines/tools/Jenkinsfile.example2 b/...idelines/development/Jenkinsfile.example2 → ...ent-guidelines/tools/Jenkinsfile.example2
diff --git a/...idelines/development/Jenkinsfile.template → ...ent-guidelines/tools/Jenkinsfile.template b/...idelines/development/Jenkinsfile.template → ...ent-guidelines/tools/Jenkinsfile.template
diff --git a/doc/development-guidelines/tools/creating-new-repository.rst b/doc/development-guidelines/tools/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/...es/development/docker/Dockerfile.template → ...idelines/tools/docker/Dockerfile.template b/...es/development/docker/Dockerfile.template → ...idelines/tools/docker/Dockerfile.template
diff --git a/...opment/docker/Jenkinsfile.docker.template → .../tools/docker/Jenkinsfile.docker.template b/...opment/docker/Jenkinsfile.docker.template → .../tools/docker/Jenkinsfile.docker.template
diff --git a/doc/guidelines/development/docker/docker.rst → ...opment-guidelines/tools/docker/docker.rst b/doc/guidelines/development/docker/docker.rst → ...opment-guidelines/tools/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/procedures/dockermacm1.rst → ...t-guidelines/tools/docker/dockermacm1.rst b/doc/procedures/dockermacm1.rst → ...t-guidelines/tools/docker/dockermacm1.rst
@@ -13,13 +13,13 @@ Once you have docker desktop running open the settings (Cmd ,)
 
 - In the General settings make sure 'VirtioFS' is selected.
 
-.. figure:: ../images//DockerSettingG.png
+.. figure:: ../../../images/DockerSettingG.png
    :name: fig-dockerg
    :alt: Docker General Settings
 
 - In the Features in Development settings select 'Use Rosetta for X86/amd64 emulation on Apple Silicon'
 
-.. figure:: ../images//DockerSettingD.png
+.. figure:: ../../../images/DockerSettingD.png
    :name: fig-dockerd
    :alt: Docker Development Settings
 

diff --git a/doc/guidelines/development/docker/index.rst → ...lopment-guidelines/tools/docker/index.rst b/doc/guidelines/development/docker/index.rst → ...lopment-guidelines/tools/docker/index.rst
diff --git a/...ines/development/docker/setup.sh.template → ...guidelines/tools/docker/setup.sh.template b/...ines/development/docker/setup.sh.template → ...guidelines/tools/docker/setup.sh.template
diff --git a/doc/development-guidelines/tools/index.rst b/doc/development-guidelines/tools/index.rst
@@ -0,0 +1,13 @@
+#####
+Tools
+#####
+
+List of development tools and resources used by TSSW.
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    *
+    docker/index
+
diff --git a/doc/guidelines/development/jenkinsfile.rst → ...elopment-guidelines/tools/jenkinsfile.rst b/doc/guidelines/development/jenkinsfile.rst → ...elopment-guidelines/tools/jenkinsfile.rst
diff --git a/doc/procedures/pre_commit.rst → ...velopment-guidelines/tools/pre_commit.rst b/doc/procedures/pre_commit.rst → ...velopment-guidelines/tools/pre_commit.rst
diff --git a/doc/guidelines/development/unit_testing.rst → doc/development-guidelines/unit_testing.rst b/doc/guidelines/development/unit_testing.rst → doc/development-guidelines/unit_testing.rst
diff --git a/doc/procedures/versioning.rst → doc/development-guidelines/versioning.rst b/doc/procedures/versioning.rst → doc/development-guidelines/versioning.rst
@@ -8,8 +8,8 @@ Exceptions (e.g. see the cycle build) should be well documented in the package a
 
 Tagging a version has the following rules:
 
-  * ticket branches can be tagged with ``vX.Y.Z.alpha.N`` or ``vX.Y.Z.beta.N`` tags
-  * The develop branch can be tagged with ``vX.Y.Z.rc.N``
+  * ticket branches can be tagged with ``vX.Y.Z-alpha.N`` or ``vX.Y.Z-beta.N`` tags
+  * The develop branch can be tagged with ``vX.Y.Z-rc.N``
     If your code is using ts_xml develop branch then the CSC release must be tagged here.
   * Main branch is reserved for main tags: ``vX.Y.Z``
     Any releases tagged from here must be compatible with the current released version of ts_xml.
@@ -29,8 +29,8 @@ Where X, Y and Z are major, minor and point/hotfix respectively.
 
     .. prompt:: bash
 
-      git tag vX.Y.Z.a.N
-      git push origin vX.Y.Z.a.N
+      git tag vX.Y.Z-alpha.N --annotate -m "Add release message here."
+      git push origin vX.Y.Z-alpha.N
 
   .. tab-item:: Tag beta
 
@@ -39,8 +39,8 @@ Where X, Y and Z are major, minor and point/hotfix respectively.
 
     .. prompt:: bash
 
-      git tag vX.Y.Z.b.N
-      git push origin vX.Y.Z.b.N
+      git tag vX.Y.Z-beta.N --annotate -m "Add release message here."
+      git push origin vX.Y.Z-beta.N
 
   .. tab-item:: Tag release candidate
 
@@ -50,8 +50,8 @@ Where X, Y and Z are major, minor and point/hotfix respectively.
 
     .. prompt:: bash
 
-      git tag vX.Y.Z.rc.N
-      git push origin vX.Y.Z.rc.N
+      git tag vX.Y.Z-rc.N --annotate -m "Add release message here."
+      git push origin vX.Y.Z-rc.N
 
   .. tab-item:: Tag release
 
@@ -60,6 +60,6 @@ Where X, Y and Z are major, minor and point/hotfix respectively.
 
     .. prompt:: bash
 
-      git tag -a vX.Y.Z
+      git tag -a vX.Y.Z --annotate -m "Add release message here."
       git push origin vX.Y.Z
 
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/doc/development-guidelines/xml/index.rst b/doc/development-guidelines/xml/index.rst
@@ -0,0 +1,10 @@
+
+###
+XML
+###
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    *
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/deployment/index.rst b/doc/guidelines/deployment/index.rst
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.
 
+.. toctree::
+  :glob:
+  :maxdepth: 1
+  :hidden:
 
-Procedures
-##########
-This section outlines procedures that our team uses such as workflow, jira and sprint management.
+  team/index
+  work_management/index
+  development-guidelines/index
 
-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.
+Team
+####
 
+Basic information about the TSSW team and our culture.
 
-.. toctree::
-  :glob:
-  :maxdepth: 3
+- :ref:`onboarding_checklist`
+- :ref:`culture_and_standards`
 
-  procedures/index
+Communications
+##############
 
+TSSW adopts the same communications channels and procedures as Data Management (DM).
+For more information see `DM Communications`_ Guidelines.
 
-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.
+.. _DM Communications: https://developer.lsst.io/#part-communications
 
-.. toctree::
-  :glob:
-  :maxdepth: 3
+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.
 
-  guidelines/index
+.. _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/index.rst b/doc/procedures/index.rst
diff --git a/doc/procedures/additional-resources.rst → doc/team/additional-resources.rst b/doc/procedures/additional-resources.rst → doc/team/additional-resources.rst
diff --git a/doc/team/culture-and-standards.rst b/doc/team/culture-and-standards.rst
@@ -0,0 +1,6 @@
+
+.. _culture_and_standards:
+
+##################################
+Team culture and conduct standards
+##################################
diff --git a/doc/team/index.rst b/doc/team/index.rst
@@ -0,0 +1,11 @@
+####
+Team
+####
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    culture-and-standards
+    onboarding-checklist
+    additional-resources
diff --git a/doc/team/onboarding-checklist.rst b/doc/team/onboarding-checklist.rst
@@ -0,0 +1,8 @@
+
+.. _onboarding_checklist:
+
+####################
+Onboarding checklist
+####################
+
+TBD