How to Contribute?

We want Nexus to serve also as a place where members of the community can share their knowledge. This guide answers the question, how to contribute to Nexus?

What kinds of resources are hosted on Nexus?

Any content (original or external) that can help make the practice of ML/AI more connected, accessible, efficient, and reproducible is welcome on the Nexus platform! This includes, but is not limited to…

• 🧠 Educational materials: Explore a library of educational materials (workshops, books, videos, etc.) covering a wide range of ML-related topics, tools, and workflows, from foundational concepts to advanced techniques.

• 🛠 Models, code, and more: Learn about popular models, tools, and datasets that you can leverage for your next ML project.

• 🧬 Applications & stories: Discover a curated collection of blogs, papers, and talks which dive into real-world ML applications and lessons learned by practitioners.

Disclaimer: The crowdsourced resources on this website are not endorsed by the UW-Madison and have not been vetted by the Division of Information Technology.

Need inspiration for a good topic to post about?

An ever-expanding list of requested resources can be found on the Issues page (on GitHub). Search for open issues that have the “Resource” label to check out some of our top priorities. If you’d like to tackle a given issue, please comment on the issue to let others know.

What makes a good post?

Creating a useful and engaging post for the ML+X Nexus involves a few key elements to ensure it is beneficial for the community. Here are some general guidelines to follow:

Clear and concise title

The title should accurately reflect the content and main focus of the post. It should be engaging and specific, allowing readers to quickly understand what they can expect.

Detailed description

Provide a comprehensive overview of the resource or topic. This should include:

• Purpose and scope: Clearly state what the resource covers and its main objectives. Explain why the content is valuable and how it can help practitioners.

• Key features: Highlight the unique aspects or strengths of the resource. This could include practical examples, interactive elements, or real-world applications.

• Strengths and weaknesses: Provide a balanced view by discussing both the strengths and any potential limitations of the resource. This helps users make informed decisions about whether the resource is right for them.

Prerequisites

List any necessary background knowledge or skills required to fully benefit from the resource. This helps set expectations and ensures that users are adequately prepared. Include links to additional resources or tutorials that can help users gain the required knowledge.

Estimated time to complete

Offer an estimate of the time commitment needed to complete the resource. This helps users plan their learning activities and manage their time effectively.

Accessibility and usability

Ensure the resource is easy to access and use. We want the majority of resources on Nexus to be free and open source (with possibly a few rare exceptions for tools/resources in high-demand). Provide clear instructions on how to navigate and utilize the content. If the resource is hosted externally, include a direct link and any necessary login or access information.

Additional related resources

Include links to related materials or further readings that can enhance the user’s understanding and provide more in-depth knowledge on the topic. This can include books, articles, other workshops, or case studies. When possible, link to any relevant materials which are already hosted on the Nexus platform.

Examples of good posts

Please see below for a list of resources that meet our platform’s standards. You can use these examples in conjunction with the template files provided in the next section to create your post. You can click “Improve this page” near the top right of each resource page to view the corresponding quarto file (.qmd) and code, or find the file in the GitHub repo.

External content

• Learn: Workshop
• Learn: Book
• Learn: Video
• Application: Video
• Toolbox: Data

Original content

• Learn: Guide
• Learn: Notebook
• Application: Blog

How to make a new post with GitHub?

Prerequisites

You do not necessarily need specific training in anything, but you will need to use git and GitHub:

• Some familiarity with git or GitHub Desktop (clone, pull, commit, push)
• A GitHub account and some familiarity with GitHub (Fork, Issues, Pull Request)

GitHub collaboration model

We follow GitHub’s collaboration model, so the general idea to make a post or edit a document is the same. The high-level steps include :

1. Get started with git and GitHub
2. Create an issue announcing your plan to add a resource — see ML+X Nexus Issues
3. Fork the ML+X-Nexus repository
4. Clone the forked repository onto your local machine
5. Create a new branch
6. Write the post
   • (optional) Preview and iterate
7. commit and push the changes
8. Make a pull request
9. Wait for review

If you don’t know how to use Git / GitHub already, it can be a little intimidating at first. A friendlier alternative could be to download GitHub desktop and add your post using the instructions provided below. If you’d like to learn more about GitHub Desktop, check out the Version Control with GitHub Desktop guide on Nexus. If you need additional help (and work in a research lab at UW-Madison), you may also seek help at the Data Science Hub’s office hours (“Coding Meetup”).

1. Get Started with GitHub Desktop (recommended if you’re new to Git and GitHub)

1. Go to the GitHub Desktop website and download the application for your operating system. Install GitHub Desktop by following the on-screen instructions.
2. Open GitHub Desktop and sign in with your GitHub account. If you don’t have one, you will need to create your GitHub account first.

2. Create an Issue on Nexus GitHub

Before you start writing your content, create an issue on the Nexus GitHub to announce your intended addition. This helps the Nexus development team keep track of new contributions and provides an opportunity for feedback.

1. Go to the Nexus GitHub Issues page
2. Click on the New Issue button.
3. Title the issue with the name of your resource, and add a “Resource” label/tag (found on right side panel of issue post).
4. Describe why you think this resource should be included on the Nexus platform.
5. Wait for feedback: Wait for one of the Nexus developers to provide feedback or comments on your issue before proceeding.

3. Fork the Repository

The purpose of a Fork is to create a copy of the original repository that can be syncronized. In an open-source collaboration, the original repository will not allow you to make edits directly. Instead, you will update your Fork and then ask the original repository owners to integrate your changes through a Pull Request (PR), which you will do in step 8.

1. Go to the ML+X-Nexus repository on GitHub.
2. Click the Fork button at the top-right corner of the page.
   • This will create a copy of the repository under your GitHub account.
   • You will now be able to make changes to your Forked copy of the repository.

4. Clone the Repository to Your System to Your Local System

Cloning your Fork to your local filesystem will allow you to use your development environment of choice to make changes.

1. From your new forked version of the repo on GitHub, click the green Code button to copy the HTTPS URL of the fork
2. In GitHub Desktop, click on File > Clone Repository.
3. Paste the URL and click Clone

5. Create a New Branch

It is common practice to create a new branch anytime you perform work as a new feature, update, or fix. This is often called a “feature branch”. The name comes from the idea that each feature should have its own branch, in an effort to keep things tidy.

1. In GitHub Desktop, click on Branch > New Branch.
2. Name your new branch descriptively based on the resource type and name (e.g., workshop-introDL, video-NeurIPS2024, etc.).

6. Write Your Post

This is where you make changes to add your new content. Often times this starts by copying a template of your desired content (links below) into the desired folder and editing it to reflect the content you want to share.

1. Open your favorite text editor or IDE (e.g., Visual Studio Code, Sublime Text).
2. Write your post in the appropriate format. Follow the guidelines below, making use the template files provided.

Resource templates

If applicable, start with one of the relevant template files linked below. There are comments in each template that will help you make the appropriate edits for your resource. You can also check out how other posts have been formatted by clicking “Improve this page” from a given post’s webpage. This will bring you directly to the qmd file for that post.

• Educational - blog

• Educational - book

• Educational - video: lectures, forums, seminars, etc.

• Educational - workshop

• Application - blog

• Application - video

• Toolbox - data

• Toolbox - model

• Toolbox - library

Where to place your resource qmd file

We want the site to be constantly evolving with the community, and our intention is to keep the contributions to the site as free as possible. However, we added some sections to structure the site a little bit:

├── Applications
│   ├── Blogs
│   ├── Videos
│   ├── Papers
│   ├── Playlists
├── Learn
│   ├── Blogs
│   ├── Books
│   ├── Guides
│   ├── Notebooks
│   ├── Videos
│   ├── Workshops
├── Toolbox
│   ├── Compute
│   ├── Data 
│   ├── GenAI 
│   ├── Libraries 
│   ├── Models 

Note: Some subfolders may not exist yet (e.g., Code, Data) since no one has contributed a resource from one of those categories yet, and git doesn’t allow empty folders. If your resource doesn’t belong to one of the categories listed above, you may add a new one. We’ll discuss this new category when we review your initial “Issue” announcing the resource addition.

How to preview new content

It is possible to preview the page you are creating on your local machine before you make the pull request, or even commit any changes. This requires Quarto to be installed on your local machine. Note that this can be very helpful, but try not to spend too much time iterating without committing, pushing, and completing the Pull Request process. You can always come back to this step and improve the content after it is submitted for review.

1. Install Quarto on your local machine
2. Open terminal/shell/command line and run the quarto preview <my_new_content.qmd> command (replace <my_new_content.qmd> with your content file)
3. Wait for the files to render (this can take a while the first time as it renders all pages the first time)
4. A browser window should open with your version of the ML+X Nexus page
5. Review your changes

While the quarto preview command is running, the content will update when it notices a change. This allows you to iterate quickly between review and editing. When you want to stop previewing, cancel the quarto preview command. Usually this is done by pressing Ctrl+C in the terminal window.

7. Commit and Push Changes

Commit and push changes to your feature branch as you work. You can commit and push as many times as you want to track the updates anc changes you’ve made.

1. In GitHub Desktop, you should see your changes listed under Changes.
2. Write a descriptive commit message (e.g., Add new resource: workshop-introDL).
3. Click Commit to your-branch-name.
4. Click on Repository > Push to push your changes to GitHub.

8. Make a Pull Request

Pull Request (PR) is the term used when you request that one branch be pulled into another. The process of combining branches is often called a merge. In this case, you will ask the original repository to merge your Fork’s feature branch into their main branch. This PR will notify the original repository owner of your request and will then be reviewed.

1. Go to your forked repository on GitHub.
2. Click on the Compare & pull request button.
3. Ensure you are merging into the “main” branch of the ML+X-Nexus repository.
4. Write a descriptive title and comment for your pull request.
5. Click Create pull request.

9. Wait for Review

Your Pull Request (PR) will need to be reviewed by the owner of the original repository.

1. One of the Nexus developers will review your pull request. They may provide feedback or request changes.
2. Address any feedback and push additional commits as needed.

How to improve an existing post?

Want to add a code-along exercise to an existing post, add your perspective, or correct a typo? Anyone is welcome and encouraged to suggest improvements to existing materials hosted on Nexus! The most straightforward way to do this is to click “Improve this page” from the post’s webpage on Nexus to suggest your edits. The below steps will walk you through this process.

Steps to improve a post on Nexus via GitHub (no software installation needed):

1. Click “Improve this page”: This will redirect you to the GitHub repository where the content of the post is stored.

2. Edit the file directly on GitHub:

   • On the GitHub page, click the pencil icon (✏️) at the top right of the file to edit the content directly in your browser. No need to install any git software!
   • Make your changes in the text editor. You can add a code-long exercise, share your perspective, or correct any typos.

3. Commit your changes:

   • After you have made your edits, scroll down to the “Commit changes” section.
   • Write a brief description of what you changed.
   • Choose the option to “Create a new branch for this commit and start a pull request.”

4. Create a pull request:

   • Click the “Propose changes” button.
   • You will be taken to a new page where you can review your changes.
   • Click “Create pull request” to submit your changes for review.

Congratulations! You have suggested an improvement to a Nexus post. The repository maintainers will review your pull request, and if everything looks good, your changes will be merged into the post.

Note: While you can make these edits directly on GitHub without any software installation, we recommend all ML practitioners learn git! Check out our git category search resources.

Questions?

If you any lingering questions on how to contribute, please feel free to post to the Nexus Q&A on GitHub. We will improve this guide based on additional questions/comments we receive.