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

Pull latest changes from upstream

$ git fetch upstream master
$ git merge upstream/master --ff-only

Updating a853c6a7..dc641090
Fast-forward
 apod/CHANGES.txt                 |  3 +++
 ... other changes here
 9 files changed, 85 insertions(+), 16 deletions(-)

The above should be done at the start of all new development, so you are working off the latest changes in master.

Locally branch for your work

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

We have 5 commits, and to "squash" them into a single commit we issue in "interactive rebase"

git rebase -i HEAD~5

Note the number at the end is because we're going to squash 5 commits. Change this to the number you are squashing.

You will then see a git window for squashing the commits. There is information on what to do in comments in the page it shows. For example:

pick 8c919098 Added README
pick 3f89ff22 Initial Makefile
pick 79b7d432 WIP - makefile changes
pick 95e52497 oops
pick c76e4daa Working ipify

# Rebase dc641090..c76e4daa onto dc641090 (5 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# ... other information

First notice the 5 commits are in reverse order, the oldest being at the top. Down the left side is currently the word "pick", we need to change all but the first into a "squash".

So, edit the file to look like the following (you can ignore the comment and blank lines):

pick 8c919098 Added README
squash 3f89ff22 Initial Makefile
squash 79b7d432 WIP - makefile changes
squash 95e52497 oops
squash c76e4daa Working ipify

It's always "leave the first as pick, change everything else to squash". You can use just the letter "s" instead of "squash" if you're feeling particularly lazy.

Save the file, and git will work its magic, and then ask you to change the commit message of the overall single commit you're creating.

# This is a combination of 5 commits.
# This is the 1st commit message:

Added README

# This is the commit message #2:

Initial Makefile

# This is the commit message #3:

WIP - makefile changes

# This is the commit message #4:

oops

# This is the commit message #5:

Working ipify

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.

You can now craft your final commit message for the single change you're making, e.g.

Added ipify application to test nework library json functions

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.

Save and exit your editor, and it will show git's output for the operation.

$ git rebase -i HEAD~5
[detached HEAD a10c5625] Added ipify application to test nework library json functions
 Date: Sat Dec 30 18:02:29 2023 +0000
 4 files changed, 4 insertions(+)
 create mode 100644 ipify/Makefile
 create mode 100644 ipify/README.md
 create mode 100644 ipify/ipify.c
 create mode 100644 ipify/ipify.h
Successfully rebased and updated refs/heads/xp-ipify.

Doing another git history will show you now have 1 commit.

$ git log --pretty=format:"%h %ad | %s%d [%an]" --graph --date=short -10
* a10c5625 2023-12-30 | Added ipify application to test nework library json functions (HEAD -> xp-ipify) [Mark Fisher]
* ... other commits from older work here