Nugsoft Developer Guides

9. Version Control

Git & GitHub Workflow:

To ensure consistency and maintain a clean codebase, follow a well-defined Git workflow. This will improve collaboration and help manage the development lifecycle effectively.

1. Feature Branches:
  • Create a new branch for each new feature following the naming convention feature/<descriptive-name>.
  • These branches should branch off from the develop branch.
  • Example: feature/user-authentication.
2. Bugfix Branches:
  • Use a branch for bug fixes named bugfix/<descriptive-name>.
  • These branches should also branch off from develop.
  • Example: bugfix/login-error.
3. Release Branches:
  • Create a release branch when preparing for a new release.
  • Branch off from develop and merge into both main and develop once the release is stable.
  • Use versioning in branch names (e.g., release/v1.0).
4. Hotfix Branches:
  • Use hotfix branches for urgent fixes on production.
  • These branch directly from main and merge back into both main and develop (or staging if necessary).
  • Example: hotfix/critical-login-bug.
5. Develop Branch:
  • The develop branch is the main working branch where features and bug fixes are integrated.
  • Regularly merge feature and bugfix branches into develop after review and testing.
6. Staging Branch:
  • Use a staging branch to test code in a production-like environment before release.
  • Merge develop into staging for final testing before going live.
7. Main/Production Branch:
  • The main or production branch reflects the code that is live in production.
  • Only merge code into main/production after it has been reviewed and tested in staging.
8. Pull Requests:

After committing your changes, push them to the remote branch and create a Pull Request (PR) to merge your changes with the main branch.

  • To create a PR, navigate to the branch page and click “Create a Pull Request.”
  • You’ll need to provide a title and description for the PR, and you can link it.
  • to an issue or assign it to a reviewer. You can also add labels, such as bug, feature, or enhancement
9. Code Review

Code review is a critical step before merging your code into the main branch. It ensures that the code is clean, follows best practices, and doesn’t introduce bugs or performance issues. After creating a PR, assign it to someone experienced in the codebase, ideally a senior developer.

Having two reviewers for each PR is recommended, as it helps catch more issues and promotes knowledge sharing among team members.

10. Merging Guidelines:

The final step in the GitHub workflow is merging the PR into the main branch. After the PR is approved and merged, the associated issue will be automatically closed. Don’t forget to delete the branch after merging to keep the repository clean.

  • Always merge using the pull request workflow.
  • Ensure to use squash and merge for combining commits if there are too many small or irrelevant commits.
  • Avoid force-pushing to shared branches like main or develop.

Branch Naming Conventions:

Using descriptive and consistent branch names makes it easier to track changes. Good: feature/user-authentication, bugfix/login-error, release/v1.0, hotfix/payment-issue. Bad: feature, fix, release1.

Commit Messages:

Commit messages should always follow best practices to ensure that they are informative and help others (or your future self) understand what changes were made.

1. Message Format:
  • Commit frequently rather than waiting until all work is done.
  • Write clear, descriptive commit messages that explain what you did.
  • Use the present tense, such as add, fix, or update.
  • Keep the message under 50 characters if possible.
  • Follow a convention such as Type: Short Description. For example:
    • feat: implement dashboard header
    • feat: implement dashboard main content
    • style: add dashboard styling
    • fix: fix dashboard data fetching
    • enhance: add dashboard animations
    • refactor: improve dashboard API implementation
    • docs: add API documentation for dashboard
2. Type Prefix:
  • Use a prefix to indicate the type of change:
    • feat: for new features.
    • fix: for bug fixes.
    • style: for styling.
    • enhance: for code improvements.
    • docs: for documentation updates.
    • test: for adding or updating tests.
    • refactor: for code changes that neither fix a bug nor add a feature.
    • chore: for miscellaneous tasks (e.g., build scripts).
3. Descriptive Messages:
  • Ensure that the commit message explains why the change was made, not just what was changed.
    • Good: feat: implement dashboard header.
    • Bad: fixed stuff.
4. Breaking Changes:
  • If the commit introduces a breaking change, indicate this in the commit message by adding a BREAKING CHANGE: note.
  • Example: BREAKING CHANGE: updated authentication method to OAuth 2.0.

Tagging and Versioning:

1. Tagging:
  • Tag each release with a version number.
  • Use Semantic Versioning: MAJOR.MINOR.PATCH.
  • Example: v1.0.0, v1.2.1.
2. Versioning:

Major: for incompatible API changes. Minor: for backward-compatible new features. Patch: for backward-compatible bug fixes.

3. Release Notes:
  • Include release notes with each release to document changes.
  • Use a tool like GitHub Releases to manage release notes.
  • Include a link to the release notes in the release tag.
  • Example: v1.0.0.

This workflow might seem like a lot initially, but with practice, it will become second nature.

Back to Top