Skip to content

Latest commit

 

History

History
124 lines (77 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

124 lines (77 loc) · 10.2 KB
Raw

How to Contribute

We are thrilled that you're considering contributing to the Data Science Workbook!
Your guest contributions are vital for the success of this project.

If you're eager to get involved but unsure where to start, don't hesitate to reach out to us via email ([email protected]) or by asking a question in the (DSW Discussion) channels.

Contributing is streamlined and user-friendly, as the Data Science Workbook operates on a GitHub repository backend.

There are a few ways to do this:

  • A. Using Github pull requests (preferred).
  • B. Edit online in GitHub.
  • C. Send your markdown file directly to Alex or use [email protected].

A. Manage Your Fork with Git CLI

The preferred pathway for contributing to the Data Science Workbook involves forking the DSW repository, cloning it to your local machine, and adeptly managing your commits with Git. This approach not only ensures the safety of your progress but also streamlines the process of creating a pull request to the original repository.

Here’s a basic guide to get started:

  1. Fork the Repository:
    Begin by forking the repository on GitHub, ISUgenomics/datascience-workbook.

  2. Clone Locally:
    Clone the project to your machine to make your changes locally.

  3. Branch Out:
    Create a new branch on your local repository to safely work on your contribution.

  4. Edit or Add Content:
    Make your changes or additions to the files with your preferred editor (e.g., VSC is a good choice).

  5. Commit Your Changes: Commit your changes to your branch, detailing what you've modified or added.

  6. Sync with Main: Ensure your branch is up to date by merging the latest changes from the “upstream” main branch.

  7. Push to Your Fork: Push your branch with the changes back up to your GitHub fork.

  8. Submit a Pull Request: Finally, submit a pull request so we can review your enhancements.


PRO TIP:
For a hands-on introduction to GitHub repositories and mastering git version control, dive into the GIT - a distributed version control system tutorial featured in the Data Science Workbook. It's designed to offer practical guidance and experience, ensuring you confidently navigate and contribute to repositories. Start your journey with this Hands-on tutorial section and elevate your skills by engaging in its interactive, step-by-step content.

B. Manage Your Fork in GitHub's GUI

If CLI-based method doesn't quite fit your style, don't worry, there's more than one way to contribute!
You can handle everything smoothly right within GitHub's interface, and there's no need for any complex tools!

  1. Fork it!
    Head to the GitHub repo ISUgenomics/datascience-workbook ⤴ and hit that Fork button on the top-right. It's like grabbing a personal copy to play with.

  2. Add Your Magic:
    In your new forked repo, navigate to the desired section/directory and then look for the Add file button on the upper-right. Click it and choose to create a new file or upload an existing one.

  3. Edit Away:
    If you're creating a new file or want to tweak an existing one, GitHub's online editor is super handy. It's pretty straightforward – just like editing a doc online.

  4. Commit Your Changes:
    After making your edits, scroll down to commit your changes. Give a brief description of what you did, so it's clear what's going on.

  5. Submit a Pull Request: Once you're all set, create a Pull Request so we can review your enhancements. This sets the stage for your contributions to be reviewed and, fingers crossed, merged into the main DSW project!

C. Send your ready-made markdown file

If you prefer a more independent approach, you can simply send your markdown file straight to us using email address:
[email protected] or [email protected]
and we'll take it from there. When submitting your markdown file, please include a brief yet meaningful description of its contents and specify the section of the Data Science Workbook where you believe it fits best.

PRO TIP:
Markdown is a user-friendly markup language that even supports HTML and CSS styling, making it versatile for various needs. If you're new to Markdown or want to brush up your skills, check out tutorial Introduction to Markdown in the Data Science Workbook. It'll guide you through the basics and some advanced tips, ensuring you're all set to create an impactful file.

Your contributions are invaluable, and we're excited to see what you've crafted!

Where to find files?

If you're not certain about the location of the content you wish to edit, head to theIndex tab in the Data Science Workbook. Locate the appropriate section, access it, and then check the tutorial's URL address. This URL reveals the file's path, mirroring its location in the associated GitHub repository's file system.

Commiting changes

Please send a GitHub Pull Request to datascience-workbook with a clear list of what you’ve done (read more about pull requests). Please follow our writing conventions (below) and make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits.
One-line messages are fine for small changes, but bigger changes should look like this:

$ git commit -m "A brief summary of the commit
>
> A paragraph describing what changed and its impact."

Writing conventions

Dive into our code, and you'll soon become familiar with its flow. :)
We prioritize readability to ensure a smooth learning experience.

  • While we appreciate every contribution, please refrain from self-promotion.
  • We advocate for methods that are not only generalizable but also practical.
  • We highly encourage the use of public datasets in examples, making it easier for others to follow along and replicate the tutorials.
  • To consistently find the images for each chapter, images should be saved in the assets folder of each section. Please no copyrights!
  • Use best practices whenever possible. There might be many ways to do things, but the goal here is to make it smooth for beginners without being too confusing.
  • Keep your code as clear as your thoughts – thorough commenting and solid documentation are key, making it a breeze for others to understand and build upon your work.

How else can you help?

The best starting point for lending a hand is to dive into the vibrant (Discussions) on the DSW GitHub platform, where sharing ideas, sparking conversations, and creating issues can significantly contribute to the project's growth and success.

1. Testing/reviewing published workflows:
If you are following a particular protocol, please let us know if it worked or not. Also, we would be grateful if you let us know if changes were necessary to get it working! If you are familiar with GitHub, you can also make changes and send us the pull request. We only request that you include why the changes were necessary when submitting your pull request.

2. Correcting typos or grammar:
Typos and bad grammar can make a methods section difficult to read. If you have better way to elaborate a process, we encourage your contribution. If this is the case, please make those changes and send us the pull request. Alternatively, if a section is not clear or hard to replicate you can also open a issue/bug to ask for an expansion of the existing explanation.

3. Contributing to sections of published methods
In bioinformatics there are many ways to answer the same question. It is also true that using a particular method over another may influence the final results. Hence, we encourage the addition of alternative methods to the existing workflows that may be more adaptable to your organism or circumstances. Otherwise, please follow existing conventions, and explain why any methodological changes may be necessary.

4. Adding new protocols/methods
Are we missing a favorite topic of yours? Well, we were just waiting for you to write that section! We are very glad that you noticed it, please add your section of interest and send us the pull request.

5. Suggesting topics
If you’re working on a project and you’re stuck with not knowing how to proceed, then please provide us the list of topics for which you may need methods. We will add it to our list or increase the method’s priority in our development of this workbook.

6. Sharing your methods with us
Not time to write or add methods? No problem! Just send us your methods/protocols of doing things, either as published papers, simple writeup, weblink, wikipage, whatever the form it is. We will try to convert it and add it our workbook, crediting you! You will also be added as contributor.

7. Anything missing that may make the workbook more useful?
It can be anything, please feel free to get in touch with us! We will be more than happy to hear your opinion and adjust the workbook to make it more suitable to your needs.