GoodGitPractices

This is a brief cheat sheet for good practices as we use Github for QUDT. For general guidance on contributing to public projects on Github, please see this guidance, and in particular the section on submitting a pull request. There are essentially three stages:

Making changes to file(s)

Ensure you are up to date on your fork of the repo:

    git checkout main
    git pull

Create a new branch for your work. Please name your branch beginning with your initials, a hyphen, then some topical name:

    git checkout -b srr-mynewbranch

Do all your changes and additions and testing on this branch (srr-mynewbranch in above example). This might last for days or more.
Check that all the changed files are the ones you intended using the 'git status' command below.

    git status

If so, add them for tracking (you can also add individual files or files satisfying regular expressions):

    git add -A

Frequently commit, so that each change can be tracked and rolled back if needed.

    git commit -m 'Descriptive message about the change'

Keep your fork in sync with the QUDT remote, and bring in any latest changes in main before you push by merging:

    git checkout main
    git pull
    git checkout srr-mynewbranch
    git merge main

If you have Maven installed locally, validate the files with Maven (see how to set up your build environment). If you don't do this step, you must do step 10 below.

   mvn spotless:apply install
   mvn install

Push your branch to the remote. The first time, you'll need to create the branch on your remote fork:

    git push --set-upstream origin srr-mynewbranch

Later, when you are on your branch, you can just say

    git push

If you did not validate the files locally using Maven, do it now on the GitHub website:

a. Go to the GitHub website for your fork after you pushed your changes.
b. Create a Pull Request to merge your new branch into the main branch on your fork. Be careful with this step, because the default behavior on GitHub is to create the Pull Request to merge your new branch to the main branch on the qudt-public-repo main branch. That is not as good because you will not be able to readily invoke any of the Actions that are available, and the automatic workflow will halt until one of the QUDT codeowners approves the workflow run. So when creating the Pull Request, make sure to select the destination of the PR to be your own fork's main branch.
c. The automatic workflow will validate your changes. Once the Pull Request has been created, the workflow will run each time you push from your local machine.

Once you have passed validation, submit a Pull Request from the main branch on your fork, to the main branch on the qudt remote.

Before Submitting a pull request

Each PR will be squashed (all commits will be aggregated into one). The admins will try to create a good commit message from your commit history, but if you squash your commits before submitting the PR, you have more control over that message.

Please use this checklist:

I have built the project locally with mvn install and it succeeded, or I validated my branch on the GitHub website as described above
I have added an entry to the CHANGELOG.md

Submitting a pull request for review

Go to the Github website once you have pushed your branch.
Navigate to the code -> branches tab.
Click "New pull request". Pay attention to what the pull-downs say about what repository and branch is being merged into what other repository and branch.
Select your own fork/branch as source and the qudt/qudt-public-repo main branch as target.
Give the qudt admins access to your branch, so they can fix minor things without having to get back to you (speeds things up)
Submit the pull request
Wait until the results of the server-side build is displayed. If there is a problem, have a look at the details and try to fix it. If you cannot, the admins will look into it.