Introduction to XGC’s Git Workflow

The XGC codes are organized in three separate, private repositories on Github under the PrincetonUniversity organization (abbreviated PU in the remainder of this document):

• PrincetonUniversity/XGC-Devel: The current, actively developed versions of the XGC code (XGC1, XGCa, XGCs). All XGC developers use this repository as basis for their work.

• PrincetonUniversity/XGC-User: A read-only (except for repo admins) repository with regularly updated releases of XGC-Devel. All code in XGC-User is stable and safe for use by inexperienced XGC users. This repo is intended for pure XGC users (who do not develop code) and new XGC developers for the purpose of training.

• PrincetonUniversity/XGC-Full-f: Legacy code that has been developed in past SciDAC funding periods (e.g. XGC0, the full-f version of XGC1). This legacy code will undergo only modest development and maintenance work.

Members of XGC-Users have access to the XGC-User repository, and members of XGC-Full-f Users have access to the XGC-Full-f repository. The teams XGC Developers and XGC Admins are subgroups of the XGC-Users team. Members of XGC Developers have read-access to the XGC-Devel repository, and members of XGC Admins have administrator privileges on all three XGC repositories.

Organization of and workflow for the XGC repositories

Generic resources:

• A nice comprehensive description of Git workflows

• Stackexchange

• Ask Robert Hager (rhager@pppl.gov), Seung-Hoe Ku (sku@pppl.gov), Aaron Scheinberg (aaron@jubileedev.com), Brad King (brad.king@kitware.com) or Zack Galbreath (zack.galbreath@kitware.com) for help.

• Workflow for XGC-User
• Workflow for XGC-Devel and XGC-Full-f
  • Brief description of the workflow
  • Use of forks
  • Feature branch workflow inside a fork
  • Management of Branches
  • Exceptions from the Fork/Feature-Branch workflow
  • Pull Requests
  • Policy for large files
  • Automated Testing of Pull Requests
  • XGC Coding Guidelines
    • Basics
    • Formatting
    • Function/Subroutine arguments
    • Function/Subroutine
    • Doxygen comments
    • Version control (git)
    • Hardcoding
    • Compatibility
    • Runtime inputs and preprocessor flags
    • Modularity
    • Source file length
    • Testing
    • Pull requests
  • Git Cheat-Sheet