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.

If you pulled any changes down (maybe your repo hasn't been updated in a while), you can now push these latest changes to your own fork:

git push

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.

(If in your case, you only created 1 commit, then excellent, you can skip down to the section Preparing to push your changes back to GitHub below.)

$ 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.

...
[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

Preparing to push your changes back to GitHub

When you're finally happy with your changes, and have crafted the single commit, you will want to push it back to GitHub.

However, someone else may have already made changes since we started our own work, so we will want to put our changes on top of those before we push our changes back.

This is an important step.

Part of keeping a clean history, and to ensure your changes are not going to conflict with other developers changes, means doing a check to see if anyone else has made a change before you push.

Pull down the latest changes from Upstream

$ git checkout master
$ git fetch upstream master
$ git merge upstream/master --ff-only
$ git checkout xp-ipify
$ git rebase master

If successful, you have put your changes on top of the latest changes.

If git reports an error in the last stage, you will have a merge-conflict. Something in your change conflicted with changes someone else made. You will need to fix the changes, add them to your commit, and finish the rebase.

This is slightly more advanced than this page will go into, and should not happen unless you're making sweeping changes, which would probably mean you already know what you're doing. If not, and you do get a conflict, a quick google search for "git merge conflict" will guide you through what is needed, but it essentially boils down to fixing the issue in your editor, adding the changes to git, then continuing the rebase until git is happy it was able to take the changes. Your IDE of choice usually has ways to help here.

As you get used to git workflows, you will quickly recognise when there are no upstream changes, and so you will not need to rebase your changes, as there's nothing to put them on top of. However, the above is a good working example of how to switch branches, pull changes, then switch back to your own branch and move your work on top of the latest remote changes.

Push your changes

Creating a Pull/Merge Request in Github

If you're working on your own fork, and do not have direct push access to the main repository (the norm for most developers), you can push your changes to your fork, and then create a Merge Request in github.

Start by pushing your changes:

# If this is the first time you've pushed your branch to github, use the following to tell it the branch name:
$ git push --set-upstream origin xp-ipify

Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Delta compression using up to 24 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (7/7), 534 bytes | 267.00 KiB/s, done.
Total 7 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote: 
remote: Create a pull request for 'xp-ipify' on GitHub by visiting:
remote:      https://github.com/markjfisher/fujinet-apps/pull/new/xp-ipify
remote:
To github.com:markjfisher/fujinet-apps.git
 * [new branch]        xp-ipify -> xp-ipify
branch 'xp-ipify' set up to track 'origin/xp-ipify'.

Note, you only have to use the --set-upstream origin xp-ipify part once when you first push your new branch to github. After that, you can just use git push if you're pushing multiple changes to the remote. But it's best to aim for only pushing to github once if possible, unless you're asked to do some rework on your changes.

As you can see from the output, github has shown you how you can make a Pull Request, by clicking on the link.

Click the link, and edit the details of the page, and generate a Pull Request. You can mention your work in Discord, and someone will be along to look at your change and check it's in a good shape to merge into the main repo.

Congratulations, you just merged code into the main repository!

Afterwards, you can clean up your branch, by deleting it if you no longer need it.

When the code has been merged, you can go back to the start of this document, and pull the latest changes from upstream to see your changes in the main code line.

Direct pushing to github

If you have appropriate access, you can directly push your changes to the upstream repository.

To do this, if you were developing on a branch, then first rebase your branch onto master

git checkout master             # change to master
git merge xp-ipify --ff-only    # fetch the changes from your branch
git push                        # push changes to master branch of your own fork
git push upstream               # push changes to main repo

Note: It is vital you use --ff-only to ensure you do not create a merge request, and that all you are doing is changing your master branch pointer to the same place as your branch's HEAD. You can alternatively simply do git rebase xp-ipify in this example for the 2nd line, but doing merge with --ff-only doubly ensures you are not going to create merge commits.

As you should have already pulled the latest changes from master and rebased your code (as described in the previous sections), the reverse of pulling your changes into master should just be a matter of moving the master branch pointer to the same commit, and not actually having to do a merge.