Using GitHub to develop report queries for folio-analytics

Owned by Nassib Nassar
Last updated: Oct 31, 2023 by Sharon Beltaine
2 min read

This page outlines how to contribute a new SQL report query--or a modification of an existing query--using the shared community space in GitHub that has been set up for this purpose: the folio-analytics repository.  These notes assume that you have created a user account on GitHub and are logged in.

The basic steps are:

  1. Fork or Merge:  Create or update your own copy of the folio-analytics repository by following either step 1(a) or 1(b):
    1. If this is your first contribution, make a copy ("fork") of the repository at https://github.com/folio-org/folio-analytics by pressing the "Fork" button.  The original repository is called folio-org/folio-analytics, and your copy will be something like your-github-name/folio-analytics.  As you continue through these steps, pay attention to whether you are using the original or your copy.
    2. If you had already previously made a copy (fork), then you only need to synchronize your copy with the original repository by "merging" any new commits from the original into your copy.  To do this, look on your main page of your fork. You should see a message that says, "This branch is XX commits behind folio-org:main". Look for and click the "Compare" button on the right. Then, update the drop-downs to make sure that the data is flowing (right to left) from the main folio/folio-analytics repository to your forked copy:
      (your-github-name/folio-analytics) (main) ← (folio-org/folio-analytics) (main)
      If you find yourself seeing this instead:
      (main) ← (main)
      then click on "compare across forks".  Once you have set these up correctly, then create a "pull request" by pressing the "New pull request" button and follow the on-screen instructions to merge the pull request.
  2. Commit:  Make a set of edits ("commits") in your copy of the repository.  To do this, find a file you want to edit and then click the pen icon to use the editor.  After editing, don't forget to scroll down on the page, fill in the "Commit changes" form, and click the "Commit changes" button.
  3. Pull Request:  Create a "pull request" to submit your commits to the original repository.  To do this, press the "New pull request" button and then follow the on-screen instructions.  Also please ask in the reporting community for two volunteers to review your pull request, and add them as reviewers on the right side of the page.  This merge will be in the opposite direction as compared with step 1(b) above: this should merge commits into the original repository from your copy.  After the pull request has been accepted by two reviewers, your commits will be merged into the original repository.  If there are problems, a reviewer may ask you to make specific further commits; these new commits should be made in the same branch and they will automatically be added to the pull request (the changes may take a few minutes to transfer over to the pull request and/or require a browser page refresh).  After addressing reviewer comments, click on the reviewers again to ask for a new review.
  4. If you need further help with using GitHub, ask in the reporting community.