Skip to content

Task 4: Getting organized on MLDS GitHub

This task outlines our workflow using GitHub projects.

Getting Started

  1. Affiliate with MLDS Organization GitHub Page
  2. Fork the MldsExampleRepo repository (onto the MLDS organization) and rename it to {YOUR_NAME}
  3. In VS Code, open the repository, and load it in the appropriate DevContainer
  4. Once built, confirm that you can run the tests
  5. Using the VS Code GitHub Issues and Pull Request extension, add an issue to your newly forked repository --- "Update example repo to use my code".
  6. In your issue, be sure to label who the task belongs to ("Yourself"), add it to the MLDS project, specify appropriate labels (bug, feature, documentation, result), and associate it with a particular milestone (Spring, Summer, Fall, Winter). If you don't have any milestones available, be sure to add one using the {TERM}-{YEAR} scheme where the dates for each correspond to : SPRING = May 15 SUMMER = Aug 15 FALL = Dec 15 WINTER = Jan 15
  7. If the issue is achievable within the current month time-horizon, be sure to include it on the current Sprint.
  8. Proceed to use the extension to create a new branch, and commit your new code to that branch.
  9. Once your commits are complete, be sure to organize them neatly using an interactive rebase (use git rebase -i HEAD~10 to rebase the 10 most recent commits).
  10. In your rebase, ensure that your commits are precise, and accurately capture the work that was accomplished using squash to squish two commits together reword to clean up any commit messages, edit to change the commit.
  11. Once you're satisfied, create a pull request to main, ensure all tests pass, and rebase and merge.
  12. Delete the issue branch you were working on and be sure to pull the latest changes down to main.
  13. Repeat as necessary as new features are added.

Development Cycle

Every four weeks, we will have a Sprint / Group Meeting. This is an opportunity to share major research updates. Issues and pull requests can be used to track research deliverables.

For example, if you are building a neural propagator, perhaps you want to assess how well recurrent neural networks perform in comparison to traditional neural networks. An issue can be formed with the result label, that will capture the analysis that you're hoping to perform. You can break that issue into sub-issues if appropriate, and include issues like: - Develop residual network - Establish custom metric to quantify performance - Generate figure or visualization to show the performance difference

Project Maturation

Once your project has reached a sufficient level of complexity, we'll rebrand your repository into an official MLDS repo. At the moment, we have MLDS-ML, MLDS-RL, MLDS-CV, and MLDS-Astro as core repositories that provide basic functionality to spin up machine learning experiments in astrodynamics.

Writing

In addition to managing your experiments and research progress in GitHub issues, you can also include your writing as issues. For example, write paper might be a major milestone project with a particular date that needs to be composed into issues like "Write abstract", "Write Literature Review", "Format Figures", etc.

These can be logged on the issues page, and you can iteratively tackle different sections of your paper, and await review from other authors to give feedback on specific sections. This avoids the need to ask different contributors to review the entire report at once, but instead they can immediately inspect the changes and make comments directly in-line with the document.

Philosophy

  • Milestones = Major outcomes that require many issues to be solved
  • Issues = Problems that can be tackled in approximately 1 week's time
  • Sub-Issues = For issues that need to be further broken down, and may need more than 1 week to solve
  • Research labels = Visualization, Experiment