IxDF Developer Docs

Appearance

Git ​

Tl;DR: All our projects use Git with a repository hosted on GitHub. We use trunk-based development (TBD) with feature branches. Trunk branch always has main name.

Git setup ​

Global ignore ​

Note that our .gitignore files don’t contain settings to ignore special dirs and files that your tools (IDE or OS) can create (like .idea, .vscode or .DS_Store). That’s because we use global ignores (and you SHOULD also use it): Create a global .gitignore.

Multiple devices ​

If you use multiple devices, please consider configuring your git to use the same email and name on all devices. This it will to avoid confusion in the git history.

Use this command to compare configs on different devices:

sh
cat ~/.gitconfig

Git usage ​

Commit messages ​

The git commit message standards can be found in the Contributing file

Branches ​

On IxDF, we tried few approaches to work with git (including classic git-flow, GitLab flow) and ended up with trunk-based development (TBD):

  1. Create a new git branch for every feature or bugfix (by branching-off from main branch). New branch name MUST start from an issue-number and explain your issue, e.g. 4242-new-profile-page (we don’t limit you to use camelCase or snake_case or kebab-case).
  2. Create a PR for your branch that should be approved (where the base branch is main). Sometimes you can commit directly to main branch (for simple changes).
  3. Merge your PR to main branch (sometimes even without reviewing).
  4. Create a new git tag by creating a new GitHub release: it automatically runs CI/CD scripts.

Benefits ​

  • Parallel Development: isolate new development from finished work
  • Collaboration: each feature branch is a sandbox where the only changes are the changes necessary to get the new feature working
  • Release Staging Area: when the next release is branched off of main, it will automatically contain all the new stuff that has been finished.
  • Support For Emergency Fixes: you can use patch/hotfix branches to make an emergency change, safe in the knowledge that the hotfix will only contain your emergency fix. All you need is to branch-off from the latest release/tag on main branch, prepare your patch and tag your patch branch: it will run CI/CD scripts.

FAQ ​

Do we use commit squash? ​

Squash is a perfect option to combine few small local commits, but it can be harmful (as any history rewriting) on remote branches.

Also, you don’t need to squash if you follow the first principle from our CONTRIBUTING guide: “Use descriptive commit messages”.

Git blame feature, together with atomic descriptive commits, helps us to understand the reason of any change in our codebase. Adding GitHub issue number to the commit, helps us to understand the context of the change.

So, "descriptive commit messages" + "atomic commits" + "GH issue number" provides more benefits than git squash, especially for git blame. That’s why it’s our choice.

Why main branch is not protected (from direct commits)? ​

Currently, we don’t use this feature. The reason is simple: we trust our developers, as all our devs are seniors. They know when they should create a PR. You are free to create PRs for all your changes, we don’t need programmatic constraints for that.

There are a lot of cases when we want to make simple changes and don’t spend your and reviewer’s time (which is even more expensive for a multi-timezone team like ours): typo, documentation, change var name, etc.

Of course, we love to create Pull Requests. Even more: it’s mandatory for important changes.

There are few alternatives to a classic PR flow:

  • Ask to review a commit afterward on the main branch (usually just to make a developer aware of minor changes). Example.
  • Create a PR, review it yourself and merge (if it’s safe and relatively simple). Reviewing your code using GitHub UI can help you to have a fresh eye on your changes.
  • Create a PR, review it yourself, assign someone to review it and merge without waiting for feedback (if it’s safe and relatively simple). Great for PRs with safe changes, where potential feedback can be just renaming a variable or improve docs or even just to make a developer aware of changes.

Literature ​

Wants to go deeper? Here are some resources: