Development Best Practices
This section contains guidance on how to reduce development time from concept through to publishing of a new library.
Beneficial Dependencies
Some libraries are published with the intended primary audience, or in some cases the sole audience, being developers of other libraries. These libraries are published to make some of the time consuming and awkward processes of Boost-compliance easier. It is good practice for a new library developer to read the introductions to each of these libraries, and ascertain if they might be of value to the library they are developing.
| Library | Description |
|---|---|
Helps Boost library developers adapt to compiler idiosyncrasies. The range of macros can be extended, if required, with Boost.Predef. |
|
A collection of simple core utilities with minimal dependencies. The range of utilities can be extended, if required, with Boost.Utility |
|
Customizable assert macros. |
|
A common infrastructure for throwing exceptions from Boost libraries. |
|
Provides a template metaprogramming framework, useful if metaprogramming is a feature of your new library. |
GitHub Strategies
Always submit changes to a Boost repo using a Pull Request (PR), never use the GitHub website to change the contents of a repository directly.
It is good practice to bring your local repo up to date before submitting a PR, perhaps on a weekly or even daily basis - depending on the activity in the repo.
Merge commits are to be avoided. These commits happens when a local origin branch and remote branch are out of sync.
The focus is on strategies that emphasize linear history, rebasing, and collaborative discipline. What follows are the best practices that can help.
Use Rebase Instead of Merge
When integrating changes from one branch into another, use git rebase instead of git merge. This rewrites the commit history, applying your changes on top of the target branch and maintains a linear history. Keep branches short-lived and focused on specific features or bug fixes. This reduces the likelihood of conflicts and simplifies rebasing onto the main branch. Regularly rebase your feature branch onto main or the target branch to keep up with upstream changes and avoid a large, complex integration at the end. For example:
git checkout feature-branch
git rebase mainThen push changes after resolving any conflicts:
git push --forceAlways Pull Using Rebase
Configure your Git client to rebase when pulling changes, rather than creating merge commits:
git config --global pull.rebase trueWhen working collaboratively on a branch, use git pull --rebase to fetch and reapply your local changes on top of the latest commits from the remote branch.
git pull --rebase origin mainSquash Commits Before Merging
Use interactive rebasing (git rebase -i) to clean up your branch history and squash multiple commits into one meaningful commit. This keeps the repository history tidy and avoids unnecessary merge commits.
git rebase -i HEAD~n # Replace 'n' with the number of commits to squashAfter squashing, you can fast-forward the branch without creating a merge commit:
git checkout main
git rebase feature-branchUse Fast-Forward Merges
Enable fast-forward-only merges to ensure the branch history is linear. This avoids creating a merge commit.
git merge --ff-only feature-branchConfigure the repository to enforce fast-forward merges:
git config --global merge.ff onlyEnforce Commit Discipline
Avoid unnecessary commits and ensure that every commit is meaningful. Use git add -p or git commit --amend to refine commits before pushing.
git commit --amendThis ensures that when changes are rebased or fast-forwarded, the history remains clean and easy to understand.
By following these practices, you’ll avoid merge commits and maintain a clean, linear history in your Git repository while keeping the dev community happy!