Open Science Resources

CZI Open Science Program

open science for biomedical research

View the Project on GitHub chanzuckerberg/open-science

Search this site

Contributing to this project

If you have general questions or feedback about this project and do not want to create a GitHub account to interact with the project team, please see our support guidelines. If you believe you have found a security issue, please notify us (rather than submitting an issue) by emailing security@chanzuckerberg.com.

Thanks for considering making a contribution to this project! We are very happy to help share information about what tools and resources you’ve found useful, so other biomedical researchers can improve access to research deliverables as well.

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.

These contribution guidelines assume you have a GitHub account and are able to contribute via the project’s GitHub repository. If you are not familiar with GitHub, you may find it useful to read through GitHub’s Quickstart guide.

In the spirit of open science, this project is developed using the same best practices we recommend for open source software projects. If you are new to GitHub, developing content for this site is a great, low-stakes way to learn how it works! We’re happy to help you get started.

Contributions can come in a few different forms:

You can share these contributions in two main ways via GitHub:

Additional guidance on these two methods of contributing are included below.

We try to respond to issues and pull requests within two business days. For more information about the decision-making process for what content is included in this site, please see our governance documentation.

Issues

Issues in GitHub are a great way to communicate with us about this website. Browse the existing issues to see whether there is a current conversation related to your idea.

The main sets of issue labels for this project include:

You are welcome to add thoughts to existing issues, including comments and reactions to posts in the issue discussion. If no conversation about your idea currently exists, please submit a new issue. If you are filing an issue because something isn’t rendering correctly on the website, we appreciate you sharing a screen shot!

Pull requests

We accept pull requests (PRs) from forks of our repository.

PRs for website content

Organization of website content

All content for this website can be edited via markdown (.md) files representing each of the pages in the site.

Most content related to open science is found in the following sections:

Each section is represented by:

If you would like to add additional pages to a section, use one of the existing files as a template and save it in the appropriate subdirectory. Also be sure to include the new topic on the overview page and add the new topic to the table of contents. The table of contents can be manually created, or automatically added using Markdown All in One in VSCode.

Other .md files from the repository rendered as content in the site are located at the top level of the directory. These files include:

The README is not rendered in the website, and is used only for viewing on GitHub.

Tips for writing website content

GitHub Flavored Markdown is the basic method through which files are rendered for this project. This cheat sheet is a good place to look for a quick reference on markdown formatting.

Images can be added using standard Markdown syntax. If you are including an image file, please format it as png or jpg and place it in images/. Include a relative path to the image file where it should appear in the markdown file:

![Description of image](../images/image.png)

Links to other locations in the site should be prefaced with /open-science/ and reference the location and filename of the markdown file containing the content. Prepending the repository name is necessary because we render the site using GitHub Pages’ automated backend and the folder name (repository) is required to disambiguate from other websites rendered in the same organization. For example:

The trailing slash at the end of the path is optional.

It’s also possible to use Jekyll’s site variables (site.url and site.baseurl) to render links. However, if you are building the site locally, you’ll need to restart to the server to see changes using these tags take effect (even if you have enabled auto-regeneration). Given this complexity, we have chosen to generally use the more straightforward method of prepending with the repository name (open-science). For more information on formatting links, we recommend this article.

Videos can be linked as per the instructions above, or can be embedded on a page following general instructions here. The example file wistiaPlayer.html includes example code. On the page where the video should appear, place a single line of code: include wistiaPlayer.html. This code should be formatted in Liquid syntax as a tag with curly brace percentage delimiters. Alternatively, the embed code can be entered directly on a content page, as demonstrated on the Publishing data with Dryad topic page.

Submitting a PR for website content

In most cases, you’ll be able to create your PR via the GitHub web interface. the process for proposing changes via a pull request is:

  1. Fork the project
  2. Create a new branch.
  3. Alter the content on the page using the editor in the web interface.
  4. Submit a pull request to our repository from your fork’s branch containing the changes.

Each pull request should change one thing, where a thing represents an easily described idea. Because this is a website, rather than a code development project, it can sometimes be hard to identify what represents a single thing. In general, a PR for this project will affect only one section of the website (e.g., “Software and Code”). It’s ok to submit more than one pull request!

PRs for web styling

Technical information about the site

This website is created using jekyll. The instructions below should be sufficient for most folks, but additional information is available in the jekyll documentation.

The theme used for this site is minimal. Please see that project’s documentation for more information on customization, including configuration variables, stylesheets, and layouts.

The main files involving site layout, navigation, and styling include:

If you would like to make changes to the web styling, please preview your changes by building the site locally before submitting a pull request.

Previewing the site locally

If you’d like to preview the theme locally (for example, in the process of proposing a change):

  1. Clone this repository (git clone https://github.com/chanzuckerberg/open-science)
  2. cd into the project directory
  3. Run script/bootstrap to install the necessary dependencies
  4. Run bundle exec jekyll serve to start the preview server
  5. Visit the server address listed in the output to preview the site in your browser

The minimal theme also contains a minimal test suite. To run the tests:

Additional Resources