From 934e5ab386e0a0df7aa38c15ac2dd0ffbfd62d0b Mon Sep 17 00:00:00 2001 From: Sirisha Padmasekhar Date: Tue, 23 Jun 2026 15:23:31 +0530 Subject: [PATCH 1/3] Add source control best practices guide --- source/The-ROS2-Project/Contributing.rst | 1 + .../Source-Control-Best-Practices.rst | 78 +++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst diff --git a/source/The-ROS2-Project/Contributing.rst b/source/The-ROS2-Project/Contributing.rst index e775d07cc8f..07f4babeda0 100644 --- a/source/The-ROS2-Project/Contributing.rst +++ b/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 diff --git a/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst b/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst new file mode 100644 index 00000000000..fb8ef3b1142 --- /dev/null +++ b/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst @@ -0,0 +1,78 @@ +.. redirect-from:: + + Source-Control-Best-Practices + Contributing/Source-Control-Best-Practices + +Source Control Best Practices +============================= + +.. contents:: Table of Contents + :depth: 2 + :local: + +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 workspace artifacts +---------------------------------------------- + +ROS 2 workspaces generate build artifacts that should generally not be committed to source control. + +Common examples include: + +.. code-block:: text + + build/ + install/ + log/ + +These directories are commonly generated when building ROS 2 workspaces with ``colcon build``. They can be recreated locally and generally should not be committed to source control. Repository ``.gitignore`` files should exclude them. + +Before committing changes, review the files included in a commit to ensure that generated workspace artifacts have not been added accidentally. + +Editor-specific files +--------------------- + +Editors and IDEs often generate project-specific or user-specific configuration files. + +Common examples include: + +.. code-block:: text + + .vscode/ + .idea/ + +In most ROS 2 repositories, editor-specific files are not committed to source control. + +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. + +Using a 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. + +Authentication and credentials +------------------------------ + +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 and 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. + +Additional resources +-------------------- + +* `Git ignore documentation `_ +* `GitHub gitignore templates `_ +* `GitHub SSH documentation `_ +* `Git credential storage documentation `_ \ No newline at end of file From efb6677e97c1865b5a960cf47989b2ccddbd8d95 Mon Sep 17 00:00:00 2001 From: Sirisha Padmasekhar Date: Wed, 24 Jun 2026 10:29:58 +0530 Subject: [PATCH 2/3] Wrap lines to satisfy documentation style checks --- .../Source-Control-Best-Practices.rst | 54 ++++++++++++++----- 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst b/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst index fb8ef3b1142..eaf554c031d 100644 --- a/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst +++ b/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst @@ -10,12 +10,17 @@ Source Control Best Practices :depth: 2 :local: -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. +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 workspace artifacts ---------------------------------------------- -ROS 2 workspaces generate build artifacts that should generally not be committed to source control. +ROS 2 workspaces generate build artifacts that should +generally not be committed to source control. Common examples include: @@ -25,14 +30,20 @@ Common examples include: install/ log/ -These directories are commonly generated when building ROS 2 workspaces with ``colcon build``. They can be recreated locally and generally should not be committed to source control. Repository ``.gitignore`` files should exclude them. +These directories are commonly generated when +building ROS 2 workspaces with ``colcon build``. +They can be recreated locally and +generally should not be committed to source control. +Repository ``.gitignore`` files should exclude them. -Before committing changes, review the files included in a commit to ensure that generated workspace artifacts have not been added accidentally. +Before committing changes, review the files included in a commit +to ensure that generated workspace artifacts have not been added accidentally. Editor-specific files --------------------- -Editors and IDEs often generate project-specific or user-specific configuration files. +Editors and IDEs often generate project-specific or +user-specific configuration files. Common examples include: @@ -41,16 +52,23 @@ Common examples include: .vscode/ .idea/ -In most ROS 2 repositories, editor-specific files are not committed to source control. +In most ROS 2 repositories, editor-specific files are +not committed to source control. -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. +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. Using a 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. +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. +Git supports configuring a global excludes file +through the ``core.excludesfile`` configuration option. For example: @@ -58,16 +76,24 @@ For example: $ 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. +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. Authentication and credentials ------------------------------ -When contributing to ROS 2 repositories, contributors will often interact with Git hosting services such as GitHub. +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 and avoid repeatedly entering credentials when pushing changes or interacting with remote repositories. +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. +Rather than duplicating setup instructions here, +refer to the official GitHub and Git documentation +for recommended configuration steps. Additional resources -------------------- @@ -75,4 +101,4 @@ Additional resources * `Git ignore documentation `_ * `GitHub gitignore templates `_ * `GitHub SSH documentation `_ -* `Git credential storage documentation `_ \ No newline at end of file +* `Git credential storage documentation `_ From c228f68736ded1cb47fd0af99b2e5564c4f591a7 Mon Sep 17 00:00:00 2001 From: Sirisha Padmasekhar Date: Fri, 3 Jul 2026 16:04:05 +0530 Subject: [PATCH 3/3] Address review feedback for source control best practices --- .../Source-Control-Best-Practices.rst | 118 +++++++++++------- 1 file changed, 73 insertions(+), 45 deletions(-) diff --git a/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst b/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst index eaf554c031d..1577e3d77aa 100644 --- a/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst +++ b/source/The-ROS2-Project/Contributing/Source-Control-Best-Practices.rst @@ -10,19 +10,23 @@ Source Control Best Practices :depth: 2 :local: -This page highlights source control considerations commonly -encountered when contributing to ROS 2 projects. +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. +Instead, it focuses on ROS-specific recommendations and references to external resources where appropriate. -Avoid committing generated workspace artifacts +Avoid committing generated and temporary files ---------------------------------------------- -ROS 2 workspaces generate build artifacts that should -generally not be committed to source control. +ROS 2 workspaces generate build artifacts that should generally not be committed to source control. -Common examples include: +Sources of generated, temporary, and backup files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Colcon workspace artifacts +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Common workspace artifacts include: .. code-block:: text @@ -30,20 +34,21 @@ Common examples include: install/ log/ -These directories are commonly generated when -building ROS 2 workspaces with ``colcon build``. -They can be recreated locally and -generally should not be committed to source control. -Repository ``.gitignore`` files should exclude them. +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 +~~~~~~~~~~~~~~~~~~~~~~ -Before committing changes, review the files included in a commit -to ensure that generated workspace artifacts have not been added accidentally. +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. -Editor-specific files ---------------------- +IDE configuration files +~~~~~~~~~~~~~~~~~~~~~~~ -Editors and IDEs often generate project-specific or -user-specific configuration files. +Editors and IDEs often generate project-specific or user-specific configuration files. Common examples include: @@ -52,23 +57,40 @@ Common examples include: .vscode/ .idea/ -In most ROS 2 repositories, editor-specific files are -not committed to source control. +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. -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. +Before committing changes, review the files included in a commit. +Ensure that generated and temporary files have not been added accidentally. -Using a global gitignore ------------------------- +Gitignore placement options +--------------------------- -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. +Repository ``.gitignore`` +^^^^^^^^^^^^^^^^^^^^^^^^^ -Git supports configuring a global excludes file -through the ``core.excludesfile`` configuration option. +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: @@ -76,24 +98,24 @@ For example: $ 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. +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. -Authentication and credentials ------------------------------- +Credential helpers +------------------ -When contributing to ROS 2 repositories, -contributors will often interact with Git -hosting services such as GitHub. +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. +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. +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 -------------------- @@ -102,3 +124,9 @@ Additional resources * `GitHub gitignore templates `_ * `GitHub SSH documentation `_ * `Git credential storage documentation `_ + +Example ROS 2 ``.gitignore`` files include: + +* `rclcpp `_ (minimalistic example) +* `rviz `_ (reasonable example) +* `message_filters `_ (extensive example)