GitHub

GitHub is the primary platform used for source control, collaboration, and automation across Polk County’s software projects. All application code, infrastructure configuration, and related project assets are stored in GitHub repositories under the Polk County organization.

GitHub enables distributed version control using Git while providing tools for branch management, code review, issue tracking, and automated workflows. These capabilities support collaborative development, maintain code quality, and help ensure consistent deployment processes.

Purpose

GitHub supports the software development lifecycle by providing:

• Source control for application code and configurations
• Pull request workflows for collaborative code review
• CI/CD automation through GitHub Actions
• Project visibility and collaboration through issues and discussions
• Version history and traceability for all code changes

Best Practices

When working with GitHub repositories:

• Keep pull requests focused and reasonably sized.
• Write descriptive commit messages and PR descriptions.
• Ensure CI checks pass before requesting review.
• Address review feedback promptly.
• Avoid committing generated artifacts or sensitive information.

Following these practices helps maintain a clean project history and supports effective collaboration across the engineering team.

Source Control

All application code should be maintained in Git repositories hosted in the Polk County GitHub organization.

Key source control practices include:

• Commit small, focused changes with clear commit messages that follow the Conventional Commits standard.
• Use feature branches for new work or bug fixes.
• Avoid committing secrets, credentials, or environment-specific configurations.
• Keep the main branch stable and deployable.

Git history provides a complete record of changes and supports auditing, debugging, and rollback when necessary.

Pull Requests

Pull requests (PRs) are the standard mechanism for introducing code changes into shared branches.

A typical pull request workflow includes:

1. Create a feature branch

   Branch from the main development branch.

2. Implement changes

   Commit updates locally and push the branch to GitHub.

3. Open a pull request

   Describe the change, its purpose, and any relevant context.

4. Automated checks run

   CI workflows execute formatting, linting, tests, and build validation.

5. Code review

   Engineers review the changes and provide feedback.

   GitHub Copilot may provide suggestions during PR reviews, but human reviewers are responsible for final approval.

6. Merge after approval

   Once checks pass and reviews are complete, the PR may be merged.

Code Review

All changes to shared branches are reviewed through GitHub pull requests.

Pull requests provide a structured way for engineers to collaborate, review proposed changes, and validate that updates meet engineering standards before merging.

Reviews may include:

• Peer review from engineers
• Automated validation through CI workflows
• Suggestions from AI-assisted tools such as GitHub Copilot

Pull requests should remain focused in scope and include clear descriptions explaining the purpose of the change.

For detailed expectations regarding pull request size, reviewer responsibilities, and approval requirements, see the code review standards.

Continuous Integration and Deployment

GitHub Actions are used to automate continuous integration and deployment (CI/CD) workflows.

Typical CI/CD workflows include:

• Formatting and linting code
• Running automated tests
• Performing static code analysis and security scans
• Building application artifacts
• Deploying services to infrastructure environments

Automated pipelines help ensure that code changes are validated before deployment and that releases are consistent and reproducible.

Branching Strategy

Our repositories follow the standard engineering branching model based on GitHub Flow. For full details on branch creation, naming, pull request expectations, and merge practices, refer to the branching strategy standards.

Repository Naming Conventions

Repositories within the Polk County GitHub organization should follow consistent naming conventions to improve discoverability and clarity.

General guidelines include:

• Use lowercase names with hyphens.
• Choose names that clearly describe the project or service.
• Avoid abbreviations unless they are widely understood.
• Use consistent prefixes or suffixes when appropriate.

Examples:

Repository Type	Example
Web application	permit-portal
API service	permit-api
Shared library	ui-components
Infrastructure	permit-infrastructure

Consistent naming helps developers quickly identify repositories and understand their purpose within the organization.