FujiNet Development Guidelines

FujiNet is a fun project with many repositories and developers. However, that can at times lead to a turbulent git history, and lead to difficulties later down the line when someone needs to bisect the repository to find when a particular change affected some element of the project.

The following is an attempt to give people some simple instructions on how to develop in a consistent manner with git, which will lead to cleaner history, and an easier time for everyone on the project viewing and understanding changes.

Throughout this guide, I will use the fujinet-apps repo as an example, but it applies to any other repo in the project.

Git setup

Fork the target repository, and clone it to your machine

You should first fork the repository on github through your personal account, then clone it locally:

git clone [email protected]:markjfisher/fujinet-apps.git

Setup an "upstream" remote to the original repository.

This will allow you to easily fetch changes from other developers, and combine them with any changes you are also in the process of making.

You should only do one of the following:

# If you are going to create Pull Requests in GitHub (the norm for most developers)
git remote add upstream https://github.com/FujiNetWIFI/fujinet-apps.git

# If you have direct push access, then use:
git remote add upstream [email protected]:FujiNetWIFI/fujinet-apps.git

Doing New Development

Locally branch for some changes you want to make

Let's say I'm adding a new example application called "ipify" to the apps repo. It's going to be cross-platform, so I'm going to call the branch xp-ipify and commit my work into the branch.

$ git checkout -b xp-ipify
Switched to a new branch 'xp-ipify'

I'm now ready to make my changes, adding files and creating local commits as I need. Finally I want to push my work up to github, and get it into the main codebase.

Reduce the commits to a single commit

We first want to ensure we've only created a single commit, if possible, to represent the change. Changes work best if they are small and specific to some higher goal. In this example, I created 5 commits for all the changes, including "WIP" work in progress, and some fixes, etc. But we don't want to expose all those changes to everyone else, so we're going to first rebase the changes into a single commit.

$ git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short -10
* c76e4daa 2023-12-30 | Working ipify (HEAD -> xp-ipify) [Mark Fisher]
* 95e52497 2023-12-30 | oops [Mark Fisher]
* 79b7d432 2023-12-30 | WIP - makefile changes [Mark Fisher]
* 3f89ff22 2023-12-30 | Initial Makefile [Mark Fisher]
* 8c919098 2023-12-30 | Added README [Mark Fisher]
* ... other changes from before we started