Contributing guidelines

We’re glad you’re interested in contributing to this project! Before getting started, please review our Code of Conduct. We expect all interactions related to this project follow these guidelines.

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. You can contribute in two main ways via GitHub:

  • Issues: sharing bug reports and ideas for new features; requires minimal coding and/or GitHub skills
  • Pull requests: providing updates to the code and/or documentation in the repository; experience with GitHub (and potentially code) suggested

Additional guidance on these two contribution methods are included below.

Issues

Issues in GitHub are a great way to communicate with us about this project, whether it is filing a bug report (about something that doens’t quite work for you in the browser) or suggesting a new feature (adding new functionality to the browser). Browse the existing issues to see whether there is a current conversation related to your idea or problem.

You are welcome to add feedback 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 about a problem with rendering in the browser, we appreciate you sharing a screen shot by attaching a file to the conversation!

Pull requests

Pull requests (PRs) are the GitHub mechanism that allows you to suggest changes to someone else’s repository (in this case, our project!). This section includes three types of information:

  • PR workflow: the process to create and submit a PR
  • Documentation PRs: specific information about PRs involving documentation (including the project’s website and tutorials)
  • Code PRs: code style and format guidelines for PRs involving shiny and/or other scripts

PR workflow

If your PR is correcting a small typo in documentation, or if you are learning how PRs work, the most straightforward approach is to use the GitHub web interface to make changes and submit the PR. The general process is outlined below, but is also described in more detail in the GitHub Quickstart section on GitHub flow:

  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.

A member of the core team will review your PR and inform you how to proceed. (see also our GOVERNANCE document)

If you are making more complex changes involving multiple files and/or code, it is likely you will need to make your changes on a local version of the repository. The PR workflow then requires Git to be installed and accessible on your local machine, such as the GitHub Desktop app, GitHub CLI, or git command line tools.
Then the workflow becomes:

  1. Fork the project
  2. Create a new branch.
  3. Clone the project to create a local copy on your own computer.
  4. Alter the code, check to ensure the changes still allow the browser to launch, and commit your changes.
  5. Push your changes to the remote repository.
  6. Submit a pull request to our repository from your fork’s branch containing the changes.

The specific steps may differ slightly depending on the method with which you interact with Git on your own computer.

Documentation PRs

The omicser website is built using pkgdown.

When applicable, please edit the Rmd version of a file (rather than the md) version. If you would like to recommend changes to the tutorials listed under the “Articles” drop-down menu, you can find the source files in the vignettes directory.

The site will need to be rebuilt as follows for these changes to be visible on the website:

All changes from this command will need to be committed to the repository for the website to be updated.

If you are proposing changes to the front page of the website, you should edit the top-level README.Rmd file in the repository. The file needs to be knit (to create README.md) and then the site rebuilt for these changes to be published to the website.

Code PRs

These guidelines are under construction!