Best Practices for Using Git in a Team Environment

Git is an essential tool for modern software development, enabling teams to collaborate efficiently on projects while maintaining version control. However, without clear guidelines and best practices, teams can face challenges such as merge conflicts, lost changes, and inefficient workflows. The following is aimed to outline best practices for using Git effectively in a team environment, ensuring smooth collaboration and high-quality code management. While these recommendations provide a general framework, it is important to adapt them to your specific team and project needs as every development environment is unique.

Establishing a Git Workflow

A well-defined Git workflow is crucial for maintaining an organized and efficient development process. Teams should adopt a branching strategy that best fits their project requirements. Common strategies include:

• Git Flow: A structured approach using feature, develop, release, and hotfix branches, ideal for projects with scheduled releases.
• GitHub Flow: A simpler model where feature branches are merged directly into the main branch, suitable for continuous deployment.
• Trunk-Based Development: A methodology where developers frequently merge small changes directly into the main branch, reducing long-lived feature branches and encouraging continuous integration.

To ensure consistency, teams should define rules for merging code, enforcing pull requests, and requiring code reviews before merging all helps to maintain code quality and prevent regressions.

Once a workflow has been established, teams should document their Git workflows in a CONTRIBUTING.md file or a similar document to ensure consistency and onboard new team members efficiently. This document should outline:

• The chosen branching strategy
• Commit message conventions
• PR and merge guidelines
• Security best practices
• Naming conventions

Effective Branching Strategies

Branch names should be descriptive and follow a consistent naming convention to avoid confusion. Examples include:

• feature/add-user-auth
• fix/login-issue
• hotfix/motor-template-rpm-bug

Keeping branches short-lived and regularly merging them into the main branch helps prevent merge conflicts and integration issues.

Meaningful Commit Messages

Commit messages serve as documentation for the codebase and should be clear and informative. A standardized format, such as Conventional Commits, helps maintain clarity. For example:

• feat: add user authentication
• fix: resolve login issue
• refactor: optimize report queries

Each commit should be small and focused on a single change to facilitate easier debugging and rollback if necessary.

Pull Request Collaboration

A Pull Request (PR) is an essential component of collaborative Git workflows. Best practices for PRs include:

• Providing clear descriptions of the changes made
• Using draft PRs for work-in-progress contributions
• Requesting and addressing feedback promptly
• Requiring code reviews before merging to ensure quality and compliance with coding standards

Excluding Sensitive Information

Security is a critical concern when working with Git. Teams should take precautions to avoid committing sensitive data, such as API keys and credentials. Best practices include:

• Utilizing a .gitignore file to exclude local environment files
• Storing secrets in environment variables instead of hardcoding them
• Implementing tools like GitGuardian to scan repositories for leaked credentials

Keeping the Main Branch Deployable

The main branch should always be in a deployable state to ensure smooth releases and avoid last-minute debugging. Teams can achieve this by:

• Running automated tests on all commits before merging
• Requiring feature branches to be rebased with the latest main branch changes
• Using CI/CD pipelines to automate testing and deployment

Managing Merge Conflicts

Merge conflicts are an inevitable part of collaborative development. Teams can minimize conflicts by:

• Frequently pulling the latest changes from the main branch
• Using git rebase instead of git merge for a cleaner commit history
• Carefully resolving conflicts and testing changes before pushing
• Avoid committing resource.json files without accompanying view.json changes
  • This also applies to projects/*/com.inductiveautomation.perspective/session-props/props.json

Automating with Hooks and CI/CD

Git hooks and Continuous Integration and Continuous Deployment (CI/CD) tools enhance development efficiency. Best practices include:

• Using Git hooks for pre-commit linting and formatting
• Automating testing, security checks, and deployments through CI/CD tools like GitHub Actions or Jenkins
• Enforcing code quality standards through automated checks

Developing in Multiple Environments

Setting up Development, QA, and Production environments properly is essential for ensuring seamless software deployment, testing, and maintenance. By enforcing consistent configurations, secure access controls, automated deployments, and robust monitoring, teams can enhance stability, security, and efficiency. While these best practices offer a strong foundation, each organization should tailor its approach based on specific project requirements and business objectives.

Environment Parity

Maintaining consistency across Development, QA, and Production environments helps prevent unexpected deployment issues. To achieve this:

• Align dependency versions, including databases, libraries, and operating systems, across all environments where possible. There are times when having a 1 to 1 setup for each environment is not possible, especially when talking about external databases or platform integrations. Keep this in mind when setting up the respective environments.
• Utilize the same modules and Gateway setup to test the same updates across environments.
• Implement containerization (e.g., Docker) to ensure software behaves identically in different environments. See Ignition’s official Docker image.
• For advanced users, use Infrastructure as Code (IaC) tools like Terraform or Ansible to standardize configurations.

Effective Configuration Management

Properly managing environment-specific configurations is essential for reliably testing and validating system functionality. To ensure consistency and reduce errors, follow these best practices:

• Create devices to look at different sources in the different environments, such as PLCs in production and simulators in development.
• Leverage feature flags to enable or disable features dynamically without redeployment. For instance, Session Properties in Perspective, such as host, can be used to identify the current system environment. This provides the ability to conditionally enable or disable features based on context.
• Use Deployment Modes to provide the ability to override Gateway resources in different environments. For more information on Deployment Modes and how to use them, see the Gateway Deployment Modes page
• If using Docker, use a .env file to manage environment-specific settings in Docker Compose. Instead of hardcoding values directly into your compose file, reference environment variables from a separate .env file. This approach keeps configuration clean, secure, and easy to change across different environments.
• Store secrets securely. Avoid hardcoding sensitive information like database passwords, API keys, or PLC credentials directly into project scripts, named queries, or component properties. This is a major security risk and makes managing different environments difficult.

Deployment Strategy and Automation

A structured deployment approach ensures smooth transitions between environments. Consider the following:

• Automate deployments with CI/CD pipelines to streamline testing and releases.
• Maintain separate databases and storage for each environment to prevent cross-environment data contamination.
• Use staged rollout methods to reduce the risk of issues in production. For example, using a load balancer to direct traffic to a new version gradually, or to keep both old and new versions running until the new one is verified to work correctly.

Data Management Across Environments

Handling data effectively is key to testing and security. Best practices include:

• Avoid using production data in lower environments to prevent security risks. Instead, use synthetic or anonymized data.
• Implement scheduled database refreshes for QA and staging environments using sanitized production snapshots.
• Test all schema migrations in lower environments before applying them to production.

Access Control and Security

Each environment should have appropriate access restrictions to enhance security and governance. Key measures include:

• Restricting access to production environments and allowing only authorized personnel to make changes.
• Implementing Ignition’s role-based access control (RBAC) to enforce the principle of least privilege.
• Enabling the audit log and monitoring tools to track changes and detect unauthorized access.