Skip to content

Guide: Source Code Development Guidelines

Jump to bottom
Valerio edited this page Dec 19, 2025 · 5 revisions

Guide: Source Code Development Guidelines

Purpose

To outline the end-to-end workflow for contributing code to Tudatpy, from planning to merging.

Prerequisites

  • Basic familiarity with Git and GitHub.
  • A local development environment set up (see README).

Scope

This guide covers the process of communication, branching, and PRs. It does not cover specific coding style rules (see [Guide: Coding Guidelines](Guide - Coding Guidelines.md)).

Whether you are adding a new feature, fixing a bug, or enhancing documentation, following a structured workflow ensures that contributions are easily reviewable, maintainable, and seamlessly integrated into the codebase. These guidelines describe the practices and procedures used by the TUDAT-team and align with industry-standard workflows supported by GitHub Projects, Issues, and Pull Requests.

Overview of the TUDAT Workflow

The TUDAT development process is summarized in these key phases:

  1. Communicate & Plan
  2. Branch & Develop
  3. Track Progress
  4. Pull Requests & Reviews

Each phase is detailed below to facilitate consistency and clarity throughout the project lifecycle.

1. Communication & Planning

1.1. Communication Channels

Effective communication is the foundation for successful collaboration. The TUDAT-team leverages several communication channels depending on the nature of the discussion:

  • Slack:
    For immediate coordination, quick questions, clarifications, and rapid updates on your progress. Use Slack when you need real-time interaction.
  • GitHub Projects & Issues:
    To track tasks, discuss potential improvements, report bugs, and document future milestones. Issues should be detailed, include any necessary screenshots or sample code, and link to related discussions.
  • GitHub Discussions:
    For community-wide conversations and provide support to Tudat users answering technical questions.

1.2. Creating and Managing Issues

Well-constructed Issues help maintain transparency and ensure all contributions are directed in a cohesive manner. When creating a new issue, ensure the description includes all relevant information to help team members understand and address it effectively. Start by providing the context or background that explains why the issue exists, followed by any proposed solutions or suggested next steps if they are known at the time. Be sure to reference any related discussions, code snippets, or external resources that could offer additional clarity. Once the issue is submitted, assign appropriate labels to categorize it by status, type and to indicate its priority. This helps the team prioritize and track issues more efficiently throughout the development process.

  1. Creating a New Issue:
    • Use the built-in template to capture all the necessary details: 
      ## Issue Description

<!-- Provide a concise description of the issue or new feature request. Explain why this issue or feature is important. -->

## Steps to Reproduce (If a Bug)

<!-- List the steps to reproduce the bug. Include any relevant screenshots or code snippets. -->

## Expected Behavior

<!-- Describe what you expected to happen. -->

## Current Behavior

<!-- Describe what happened instead. -->

## Possible Solution or Implementation (If a Feature)

<!-- Provide suggestions or an approach to solving the issue if applicable. -->

## Additional Context

<!-- Include any other relevant context or attach screenshots. -->
  2. Assign Required Label Every issue must have exactly one label from the following category:
    • Type:
      • type: feature – New feature or request.
      • type: enhancement – Improvements to existing functionality.
      • type: bug – Problem that affects expected behavior.
      • type: documentation – Docs or README updates.
      • type: refactor – Code structure or style improvements without changing behavior.
  3. Add the Issue to the Project Board
    • Click Projects in the issue sidebar.
    • Add the issue to the Tudat development board.
    • The issue is automatically placed in No status.
    • If applicable, move it to Any time (nice-to-have, not urgent) or Next up (high priority).
  4. Keep the Issue Updated
    • As the issue progresses, update the description with implementation notes or decisions.
    • Link relevant pull requests by mentioning the issue number in PR descriptions (e.g., Closes #42).
    • When the issue status changes update it to:
      • Next up when it is ready to be picked up next.
      • In progress once work begins.
      • Pull request when a PR is opened.
      • Completed once merged/resolved.
      • Cancelled if it's no longer needed, and explain the reasoning in the issue comments.

❗ Every issue must be linked to a GitHub Project card and contain sufficient context for any team member to understand the task independently.

2. Development

In this section, we outline the structured approach for coding, testing, and integrating new contributions into the TUDAT codebase. A robust development process is key to ensuring that each change is implemented in a controlled and predictable manner. Whether you’re forking the repository as an external contributor or working directly within the main codebase as a team member, this phase covers the essential practices—from creating dedicated branches and naming them following a standard convention, to writing clear commit messages and including thorough unit tests. By adhering to these practices, each change is isolated for easy tracking, reviewed with clarity, and merged seamlessly, thereby maintaining the high quality and stability of the project.

2.1. Forking and Branching

Contributions should be isolated in separate branches to keep the main codebase stable. Follow these steps based on your role within the project:

  • Fork the Repository:
    If you are not part of the tudat-team organization, fork the repository:
    1. Go to the Tudatpy GitHub repository.
    2. Click the "Fork" button to create a copy under your GitHub account.
    3. Clone your fork locally: 
      git clone https://github.com/<your-username>/tudatpy.git
cd tudatpy
    4. Add the main repository as an upstream remote: 
      git remote add upstream https://github.com/tudat-team/tudatpy.git

Note

If you are a tudat-team member, you may branch directly in the main repository. However, even then, isolating your work in dedicated branches is highly encouraged.

2.2. Branch Naming Conventions

Maintain clear and descriptive branch names to ensure that every change can be easily traced back to its corresponding Issue:

  • Feature Branches:
    Use feature/issue-<number>-<description>
    • Example: feature/issue-128-improved-aerodynamic-model
  • Bug Fix Branches:
    Use fix/issue-<number>-<description>
    • Example: fix/issue-129-thrust-model-bug

Always branch off of the develop branch to ensure that your work integrates well with the latest changes.

git checkout develop
git pull upstream develop
git checkout -b feature/<BRANCH-NAME>

2.3. Code Implementation and Testing

A detailed plan for development supports code stability and long-term maintainability:

  • Coding Standards:
    Adhere to TUDAT's coding conventions regarding file naming, namespace structure, and function styles. Refer to the [Guide: Coding Guidelines](Guide - Coding Guidelines.md) for detailed rules.

  • Python Bindings:
    When adding new C++ functionality that should be accessible from Python, consult the [Architecture: Python Bindings](Architecture - Python Bindings.md).

  • Commit Often:
    Make small, logically grouped commits with clear, imperative messages (e.g., "Add improved aerodynamic model interface"). This practice aids in traceability and simplifies the review process.

  • Unit Tests:
    Every new feature or bug fix must include or update corresponding unit tests.
    Follow [Guide: Creating Unit Tests](Guide - Creating Unit Tests.md) for:

    • test organization and naming
    • Boost.Test (C++) and pytest (Python) conventions
    • how to run tests locally and in CI

  • Build and Test Continuously:
    Run the relevant subset locally during development. For detailed instructions on running tests via CTest or Python directly, refer to Guide: Creating Unit Tests - Running Tests. A successful test run (e.g., "100% tests passed") confirms the stability of your changes.

3. Pull Requests & Reviews

This section outlines the process for creating pull requests and conducting thorough reviews to ensure a smooth and high-quality integration of contributions. A well-crafted pull request acts as a comprehensive summary of your work, detailing the rationale, changes, and related issues while serving as a formal avenue for peer review. By following these practices, every change is evaluated for consistency, quality, and compatibility before it is merged into the main branch. Clear communication, updated code, and proactive collaboration during the review phase help maintain a robust codebase and foster continuous improvement across the team.

3.1. Synchronizing With Upstream

Before creating a Pull Request (PR), ensure your branch is updated with the latest changes from develop:

git checkout develop
git pull upstream develop
git checkout feature/<BRANCH-NAME>
git merge develop

3.2. Creating a Pull Request

Open a PR to propose merging your branch into develop. The PR process is central to peer review and quality assurance. Here are some key points:

  • PR Description:
    In your PR description, reference any related Issue (e.g., “Closes #42”). Use the following template to ensure consistency: 
    ## Description

<!-- A brief summary of the changes made, including context and rationale. -->

## Related Issue(s)

<!-- Example: Closes #123 -->

## Feature or Bug Fix Details

<!-- Provide technical details about the feature or bug fix, including dependencies or required changes elsewhere. -->

## Testing Details

<!-- Describe how the changes were tested, referencing any new or modified unit tests. -->

## Checklist

- [ ] Branch name follows TUDAT conventions (`feature/<FEATURE-NAME>` or `fix/<FEATURE-NAME>`).
- [ ] Unit tests have been added or updated.
- [ ] Code builds and runs without errors.
- [ ] Latest changes from `develop` have been merged into the branch.
- [ ] Code has been reviewed for clarity and maintainability.
- [ ] The code follows TUDAT coding guidelines.

## Additional Notes

<!-- Add any extra context, such as known issues or future improvements. -->
  • Project Board Integration:
    Once the PR is created, add it to the Review column on the project board, so the team knows it is ready for review.

3.3. Review and Merge Process

  • Continuous Integration (CI):
    TUDAT’s CI system automatically builds and tests your PR after submission. Monitor the CI status and address any issues as needed.
  • Feedback and Adjustments:
    Engage with reviewers, implement any suggested changes, and communicate if additional context is needed.
  • Merging:
    Once the PR is approved and all CI checks pass, a TUDAT maintainer merges your PR into the develop branch.

4. Ongoing Collaboration & Board Maintenance

This final phase underscores the importance of maintaining continuous team collaboration and ensuring the project board remains a dynamic, useful resource throughout the project lifecycle.

  • Regular Updates:
    Hold brief sync meetings or share asynchronous chat updates to discuss progress, address blockers, and plan next tasks. Utilize the project board as a visual guide to steer and enrich these discussions.
  • Update the Issue:
    As the issue progresses, keep its description updated with notes or decisions, link related pull requests using the issue number, and update the status label to reflect its current stage—Next up, in progress, PR, completed, or cancelled with justification.
  • Triage Incoming Issues:
    Periodically review new Issues to ensure they are accurately categorized.
    • Label each Issue appropriately and link them to the project board to maintain visibility.
    • Promptly close duplicate or outdated Issues to keep the board uncluttered.

By dedicating time to ongoing collaboration and active board maintenance, the team fosters a responsive environment that can quickly adapt to changes and maintain a clear overview of project progress.

Conclusions

By following these detailed development guidelines, you help ensure that TUDAT’s codebase remains organized, high-quality, and accessible to both new and experienced contributors. Remember:

  1. Fork-Work-Pull Request:
    Follow this workflow unless you are a tudat-team member with direct access to the main repository.
  2. Clear Communication:
    Validate ideas early and avoid duplicate work by keeping communication channels open.
  3. Descriptive Branch and Commit Practices:
    Use descriptive branch names and commit messages to simplify code tracking.
  4. Robust Testing:
    Always add or update tests to ensure new changes do not introduce regressions.
  5. Template Usage:
    Utilize provided templates for Issues and PRs to maintain clarity and consistency.
  6. Adherence to Standards:
    Follow TUDAT coding guidelines and established workflows to maintain a high-quality codebase.
  7. Continuous Team Engagement:
    Regularly update the open issue, while proactively triaging and refining the project board. This ongoing collaboration ensures that the workflow remains agile and effective, adapting to evolving team needs and project scopes.

Together, these guidelines contribute to a smoother collaboration experience and a more robust tool for our community.

Clone this wiki locally