@Albrecht:

Finally, I've put together the basis of a "Git for FLTK Contributors" article based on the above.

However, I didn't know that you can "Fetch upstream" in GitHub, hence the 3-repo system.

I used your git format-patch text, so you can use, cannibalize, delete the rest as you see fit,

especially as I'm not sure that I've got everything 100% correct until I try to set it up :-(

D.

Git for FLTK Contributors

There are basically three levels at which you can contribute to FLTK bug fixes and new features.
Each workflow has its own pros and cons and likelihood of success.


1. Ad hoc comments and code snippets on the FLTK mailing lists or via GitHub issues.

    Code submissions are always welcome, but the unstructured nature of the mailing lists
    may mean that useful contributions may be overlooked or lost in the general traffic or
    are hard to find when a developer has the time to investigate.

    The advantage of submitting a GitHub issue is that there’s a common space where
    the contributors and the developers can discuss the pros and cons of the suggestion.

    However, the FLTK code base is constantly evolving, in some areas more than others,
    and so there may only be a small window of opportunity to apply those changes.

    The other drawback is that the contributor’s name may not be obvious in the git logs.


2. Submitting patches based on an up-to-date local clone of the FLTK repository.

    Git provides a structured way of generating patch files relating to a known state or
    “commit” in the master branch of the central repository, and includes the author’s
    name and commit message(s).

    For “How to Write a Good Commit Message” see https://chris.beams.io/posts/git-commit/

    You will need to have cloned the FLTK repo but you don’t need to be a GitHub user
    with two-factor-authentication and related security apps and codes unless you wish.

    a. Make sure that your repo is up-to-date (i.e. “git checkout master ; git pull” )
    b, Create and check out a working branch (i.e. “git checkout -b working” )
    c. Edit the code, test and commit your changes
    d. Create patch file(s) using “git format-patch master..”
        Note the trailing “..” so the last argument is “master dot dot” but no spaces.

    This will create one or more patch files named “nnnn-Commit-Message-Title.patch”
    where “nnnn” is a sequence number. The patch files can be submitted as above.

    If the central repository changes you can download the latest version and re-generate
    your patch files with a relatively small amount of work:

    e. Make sure your repo is up-to-date (i.e. “git checkout master ; git pull” )
    f. Check out your working branch again (i.e. “git checkout working” )
    g. Rebase your changes (i.e. “git rebase master”)
        Your changes now appear to be based on the most recent version
    h. Create the patch file(s) using “git format-patch master..” and submit as before.

    To clean up your local repo when the patch has been accepted (or maybe rejected!)

    i. Switch back to the main branch (i.e. “git checkout master”)
    j. Delete the obsolete working branch (i.e. “git branch -D working”)


3. Creating your own FLTK fork on GitHub and submitting a pull request.

    This method involves the most up-front investment by the contributor, and a slightly
    different workflow than you might be familiar with using git in a local development team,
    but GitHub provides extra features to improve your git experience and productivity.

    First of all, go to https://github.com/fltk/fltk and create an account and fork FLTK
    to create your own “public” copy of the FLTK repository, but still on GitHub servers.
    Next you need to clone your GitHub fork to create a “private” local working repo.

    You can pull from the official FLTK repository, but you can’t push to it, no way, no how,
    unless you are a full FLTK developer. And because of changes to GitHub policy in 2021
    you can no longer push to your “public” GitHub form with only username and password.
    Whether you choose to clone via HTTPS or SSH has consequences as discussed later.

    When you clone your GitHub fork from the official FLTK repository, your fork’s “origin”
    will be the official FLTK repository, and while you can login to the GitHub site and click
    “Fetch upstream” to keep your fork in sync, I don’t think you can resolve conflicts, etc.
    Therefore it might be better to add the official FLTK repository as a remote to your local
    repo, in addition to the “origin” that points to your GitHub fork, so you can work locally.

    In your local repo, keep the master branch in sync with the official FLTK repository:

        git remote add fltk https://github.com/fltk/fltk.git
        git checkout master
        git pull fltk master        # your local repo/master is in sync with FLTK
                            # resolve any conflicts in your local repo!
        git push origin master    # your GitHub fork/master is in sync with FLTK

    Any development work you do in your local repo should be on a working branch:

        git checkout master
        git checkout -b working
        # edit, commit, rinse and repeat
        git push origin working    # your GitHub fork/working branch has your latest changes

    Login to your account on GitHub, select the working branch, issue a new pull request.

    At this point, the pull request becomes visible to everyone on the main FLTK repository,.
    They can download the branch, test the code, and offer comments to the pull request.
    When everything is agreed, a developer merges the pull request into the master branch.
    Your name and your commit messages should appear in all their glory in the commit log.

    So how does your choice of HTTPS or SHH affect pushing changes to your GitHub fork?

    If you choose HTTPS, you will need to change your GitHub account settings to enable
    two-factor-authentication (2FA) and also generate a personal access token (PAT).

    The first, 2FA, is required to login to your GitHub account on the website, and involves
    either using an app on your smartphone or program on your computer to generate an
    one-time authentication token, or receiving a one-time token via SMS (deprecated).
    I.e. once 2FA is enabled, you need username, password AND one-time token to login.

    The personal access token (PAT) is generated by GitHub when you enable 2FA and
    is used instead of your password when pushing from your local to your GitHub repo.

    WARNING:
        The PAT is only displayed once during the process of enabling 2FA and it is
        IMPERATIVE that you copy it, or write it down before you click “Next”. The
        PAT is used as “the secret” for initialising the one-time authenication system
        and the recovery codes to be used if you lose your smartphone. If you forget
        your PAT, you will need to login to GitHub using your recovery codes, disable
        and re-enable 2FA to create a new PAT (and recovery codes) and of course
        you will need to re-initialise the authentication app using the “new secret”.

    The GitHub documentation describes how to set up 2FA and mentions that there are a
    number of third party [commercial] apps are available to handle one-time authentication,
    such as 1Password, Authy, LastPass Authenticator and Microsoft Authenticator. Other tools
    are available, such as Google Authenticator, and open source tools such as FreeOTP.
    Aegis Authenticator and KeePassXC.

    An important point to note is that you need to be able to store your PAT, your “secret”,
    securely, as well as your recovery codes, in case your smartphone or computer dies.
    Some of the tools above provide central storage on their servers, others allow export to
    local files, which you can copy to secure storage as you want. They all have pros and cons.
    The choice is yours.