Add source control best practices guide

source/The-ROS2-Project/Contributing.rst

@@ -65,6 +65,7 @@ Development Guides
    :maxdepth: 1
 
    Contributing/Developer-Guide
+   Contributing/Source-Control-Best-Practices
    Contributing/Code-Style-Language-Versions
    Contributing/Quality-Guide
    Contributing/Build-Farms

source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst

@@ -0,0 +1,132 @@
+.. redirect-from::
+
+    Source-Control-Best-Practices
+    Contributing/Source-Control-Best-Practices
+
+Source Control Best Practices
+=============================
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Introduction
+------------
+This page highlights source control considerations commonly encountered when contributing to ROS 2 projects.
+It is not intended to replace Git documentation.
+Instead, it focuses on ROS-specific recommendations and references to external resources where appropriate.
+
+Avoid committing generated and temporary files
+----------------------------------------------
+
+ROS 2 workspaces generate build artifacts that should generally not be committed to source control.
+
+Sources of generated, temporary, and backup files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Colcon workspace artifacts
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Common workspace artifacts include:
+
+.. code-block:: text
+
+   build/
+   install/
+   log/
+
+The ``build/``, ``install/``, and ``log/`` directories are generated by ``colcon build`` as part of a ROS 2 workspace.
+These directories are typically created at the workspace level rather than inside individual repositories.
+
+If these directories appear within a repository, they should not be committed to source control.
+
+Python-generated files
+~~~~~~~~~~~~~~~~~~~~~~
+
+Python generates several temporary files, including the ``__pycache__/`` directory and files ending with ``*.pyc``, ``*.pyo``, and ``*.pyd`` when you run the program.
+None of these files should ever be committed to a repository.
+
+IDE configuration files
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Editors and IDEs often generate project-specific or user-specific configuration files.
+
+Common examples include:
+
+.. code-block:: text
+
+   .vscode/
+   .idea/
+
+Many ROS 2 repositories ignore editor-specific files such as ``.vscode/`` and ``.idea/``.
+Contributors should avoid committing personal editor configuration unless it is explicitly required by the repository.
+
+Editor temporary and backup files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some editors like Vim create backup files ending with ``~`` (for example, ``test.py~``) and temporary files ending with ``*.swp``, ``*.swo``, and similar.
+These should never be committed to the repository.
+
+Operating system files
+~~~~~~~~~~~~~~~~~~~~~~
+
+Operating systems may generate metadata files such as ``.DS_Store`` (macOS) and ``Thumbs.db`` (Windows).
+These files should never be committed to a repository.
+
+Before committing changes, review the files included in a commit.
+Ensure that generated and temporary files have not been added accidentally.
+
+Gitignore placement options
+---------------------------
+
+Repository ``.gitignore``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Use the following rule of thumb when deciding whether a file belongs in a repository-specific ``.gitignore`` or your global ``.gitignore``.
+
+If the file will be present on every developer's computer, put it in the repository ``.gitignore``.
+
+Global ``.gitignore``
+^^^^^^^^^^^^^^^^^^^^^
+
+A global gitignore can help prevent accidentally committing files that are unrelated to a repository, such as operating system metadata files or personal editor configuration.
+
+Git supports configuring a global excludes file through the ``core.excludesfile`` configuration option.
+
+For example:
+
+.. code-block:: console
+
+   $ git config --global core.excludesfile ~/.gitignore_global
+
+A global gitignore is useful for excluding files that are specific to a developer's machine or editor and are not intended to be committed to any repository.
+
+Credential helpers
+------------------
+
+When contributing to ROS 2 repositories, contributors will often interact with Git hosting services such as GitHub.
+
+SSH keys and Git credential helpers can simplify authentication.
+Avoid repeatedly entering credentials when pushing changes or interacting with remote repositories.
+
+Rather than duplicating setup instructions here, refer to the official GitHub and Git documentation for recommended configuration steps.
+
+Developing on shared robots
+---------------------------
+
+When developing on a shared robot or other remote system, an SSH agent can cache your unlocked SSH key for the current session.
+This avoids repeatedly entering your SSH key passphrase when interacting with Git repositories over SSH.
+Refer to the official GitHub SSH documentation for setup instructions.
+
+Additional resources
+--------------------
+
+* `Git ignore documentation <https://git-scm.com/docs/gitignore>`_
+* `GitHub gitignore templates <https://github.com/github/gitignore>`_
+* `GitHub SSH documentation <https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_
+* `Git credential storage documentation <https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage>`_
+
+Example ROS 2 ``.gitignore`` files include:
+
+* `rclcpp <https://github.com/ros2/rclcpp/blob/rolling/.gitignore>`_ (minimalistic example)
+* `rviz <https://github.com/ros2/rviz/blob/rolling/.gitignore>`_ (reasonable example)
+* `message_filters <https://github.com/ros2/message_filters/blob/rolling/.gitignore>`_ (extensive example)