CCMMF GitHub Guide for Stakeholders

[dlebauer]

CCMMF GitHub Guide

Overview

This document introduces GitHub as a communication channel for the CCMMF community. Open science is a key feature of the CCMMF, and GitHub provides a number of features that support open science. In addition to serving as a platform for public, open-source code, it facilitates collaborative development and communication. For example, it provides the community with the ability to track progress, ask questions, provide feedback, and participate in discussions.

Don't worry if it feels like too much. You can contribute in any way that suits you—whether that means watching discussions, offering feedback directly or in meetings, or diving straight into code reviews. We use GitHub to make our work easier and facilitate collaborative development, but feel free to adopt the approach that works best for you.

If what we describe here sounds like too much to do, please know that you can contribute effectively without doing all the steps we describe here: It is totally fine to watch discussions here but send your feedback through a private channel, or to jump straight to reviewing code without configuring any notifications first, or whatever other combination makes sense to you. We use GitHub because it makes our work easier, but you are not obligated to use it the same way we do.

The focus of this document is on key GitHub features with CCMMF-specific context. We link to specific pages in GitHub's own excellent documentation for additional details.

This guide will teach you how to:

• Track and review project progress in CCMMF and PEcAn repositories
• Create and manage issues to report concerns or ask questions
• Participate in discussions to share ideas and feedback
• Review pull requests and provide input
• Monitor milestones and project workflows
• Navigate and get notifications about key project repositories.

Quick Start Summary

1. Review the CCMMF Contributor Code Of Conduct.
2. Sign up for GitHub: github.com/signup.
3. Optionally, join PEcAn Slack: Slack Invite Link.
4. Watch specific repos including ccmmf/workflows, ccmmf/organization, and pecanproject/sipnet.
5. Configure your notifications: GitHub-->watch-->custom, email filters, Slack.
6. Review project tasks and milestones in the CCMMF Organization Repository.
7. Open an Issue or start a Discussion for broader conversations. Tag specific CCMMF team members.
8. Or Slack the team for quick questions or updates. It is where many conversations start.

Understanding GitHub for Collaboration

What is GitHub?

GitHub is a web-based platform for version control and collaboration:

• Public GitHub activity for CCMMF is viewable by anyone, but a
  GitHub account is required to create or comment on issues.
• If you’re new to GitHub, or if you have questions not covered here, visit the
  GitHub Docs.
• For some conversations, it can be easiest to get started on the PEcAn Project Slack

Key Concepts

• Repositories: A repository is primarily a location to store project files, including code and documentation. This is also where you can find links to issues, discussions, pull requests, and more.
• Issues: Can be used to request and discuss new features, ask questions, report bugs, and keep track of work progress - see github.com/ccmmf/organization.
• CCMMF Milestones: group key issues into project phases and deliverables.
• Discussions: Provide a place for open-ended and often higher level conversations and knowledge-sharing. This is a relatively new feature and many repositories use issues and Slack for this purpose. CCMMF has created a single project level discussion board.
• Pull Requests (PRs): This is where users can propose and discuss specific changes to code and documentation. Code contributions are welcome, but beyond this document's scope.

Navigating Key CCMMF Repositories {#navigating-key-ccmmf-repositories}

The main repositories relevant to the CCMMF project are:

• CCMMF GitHub Homepage: github.com/ccmmf
  • CCMMF 'Organization' Repository: github.com/ccmmf/organization tracking key project tasks in one place
• CCMMF Monitoring and Modeling Workflows: github.com/ccmmf/workflows
• PEcAn Project Modeling Workflow Tools: github.com/pecanproject/pecan
  • Issues and Pull Requests labeled 'ccmmf': github.com/PecanProject/pecan/labels/ccmmf
• SIPNET Simplified Biogeochemistry Model: github.com/ccmmf/sipnet

Notifications

This section describes how to keep up to date with specific projects.

Watch Repositories Selectively

1. Go to a CCMMF or PEcAn repository (e.g.,
   github.com/ccmmf/organization).
2. Click Watch at top-right.
3. Choose “All Activity”, “Participating and @mentions”, or “Custom”.
   • All Activity can flood your inbox.
   • Participating and @mentions means only emails for items you create or where you are tagged.
   • Custom lets you filter by labels or specific event types (e.g. issues, PRs).

GitHub Docs:

• About Notifications
• Following Organizations

Dashboard

• github.com provides a feed of activities from starred repositories and followed organizations and individuals.
• Start by filtering results to “Repository activity” and “Include events from starred repositories”

Email Filters

• Use your email client to filter or label GitHub notifications (e.g., “ccmmf,” “pecan,” or “sipnet”).
• It is easy to miss Email notifications. If something is critical - or you haven’t gotten a responses, @mention someone in an issue and also send an email or Slack and / or ask in a meeting.

Navigating Repositories

• Review Project Tasks and Milestones in the CCMMF Organization Repository
  • Tasks
  • Milestones.
• Check the project boards for issue tracking and task progress.
• Click on the Milestones tab in a repository to review progress.

Interactions

GitHub Issues

Providing Feedback (Commenting)

1. Review open issues (github.com/[org]/[repo]/issues).
2. Click on an issue to view details.
3. Comment with feedback or questions.
4. Reactions (such as 👍, ❤️) are often sufficient.

Creating Issues

1. Go to the Issues tab.
2. Click New Issue.
3. Provide a clear title and detailed description.
4. Click Submit new issue.

GitHub Docs: About Issues.

Discussions

GitHub Discussions can be used for general Q&A, broader ideas, announcements, polls, and announcements.

The CCMMF project discussion board is at github.com/orgs/ccmmf/discussions

Pull Requests (PRs)

GitHub Pull Requests (PRs) allow users to review and approve specific changes to code, and documentation before they are accepted into a project.

• PR interactions are similar to Issues, but have additional features for commenting on or suggesting changes to specific lines of code.
• Submitting PRs are a way of contributing code and is beyond the scope of this document - though certainly encouraged.

How to Review a PR

1. Navigate to the Pull Requests tab in the repository.
2. Open a PR and review the proposed changes.
3. Click Files changed to examine modifications.
4. Leave comments and suggest or request changes.
5. If the changes are satisfactory, click Approve.

Submitting new PRs is beyond the scope of this document, though certainly encouraged.

Alerting Team Members

@mention relevant people if you need their input:

• @dlebauer (David LeBauer)
• @infotroph (Chris Black)
• @mdietze (Mike Dietze)
• @Alomir (Mike Longfritz)
• @robkooper (Rob Kooper)

Tip: it is often helpful to follow up with a Slack message or email to alert specific people after tagging them.

Additional Resources and Support

Reach out to the CCMMF team using your favorite communication channel! If you have questions, reach out via Slack or open a GitHub issue in the
ccmmf/organization repo.

GitHub Docs

• GitHub Docs
• GitHub Issues Guide
• GitHub Discussions Overview