CONTRIBUTING.md

Contributing Guidelines

First off, thanks for taking the time to contribute! 👏👍🎉

Table of Contents

Contributing Code

How Can I Contribute?

• Reporting Bugs
• Suggesting Enhancements
• Submitting pull requests

Style guides

• git commit messages
• documentation style guide
• python style guide

Contributing Code

1. File an issue with the feature you plan on adding. This will open a channel of communication with the core developers. See suggesting enhancements for details.

2. Fork the KwanLab Autometa repository.

   You can do this here: https://github.com/KwanLab/Autometa

   Clone your fork.

   git clone https://github.com/YourUserName/Autometa.git

   Then navigate to the Autometa directory.

   cd Autometa
3. Add the KwanLab as the upstream remote.

   git remote add upstream https://github.com/KwanLab/Autometa.git
4. Check out a branch respective to the contribution you plan to make.

   Check out the hotfix branch from main if fixing a bug.

   git checkout -b hotfix main

   If adding a feature, check out a branch corresponding to the feature you wish to add from dev.

   First checkout dev

   git checkout dev

   Then checkout your feature

   git checkout -b your-new-feature dev
5. Update your local repository with the most recent updates from the Kwan Lab.

   Update the main branch if fixing a bug.

   git pull upstream main

   Otherwise update your-new-feature branch with dev and resolve any merge conflicts.

   git pull upstream dev

   Note: Whenver you return to the feature, make sure to pull from upstream to ensure you are working on the most up-to-date code.

   Update your local repository with any changes from the Kwan Lab.

   git push origin main
   or
   git push origin dev
git push origin your-new-feature
6. Ensure pre-commit hooks are installed.

   conda install -c conda-forge pre-commit
pre-commit install

7. Submit a pull request! To submit a pull request - see instructions below.

Testing code locally

If you are testing the bash workflow and have updated an Autometa entrypoint, you will need to reinstall Autometa as follows:

cd Autometa
make clean
make install

The Nextflow workflow pulls Docker images, so in order to ensure that you are running your local updated code, you must make a Docker image locally, and then tell Nextflow to use it. In the example below, newfeature is a name given to represent the branch you are working on.

cd Autometa
docker build . --tag jasonkwan/autometa:newfeature

Then, when you test the Autometa Nextflow workflow, you can run it as follows from the Autometa directory.

nextflow run . --autometa_image_tag 'newfeature'

How can I contribute?

Reporting Bugs

Note: If you find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.

When submitting a bug report, please follow the bug report template.

Suggesting Enhancements

Feature requests may be submitted by creating a new issue. When creating this issue, please follow this template. After your feature request has been submitted, a maintainer will respond with a determination of whether this feature is appropriate for Autometa. If a maintainer has not responded within a reasonable time period, you can notify the Autometa team. See notifying the team for details.

Pull Requests

Pull requests have several goals:

• Maintain Autometa's quality
• Add features that are important to users
• Enable a sustainable system for Autometa's maintainers to review contributions

Please follow these steps to have your contribution considered by the maintainers:

1. Follow all instructions in respective bug_fix or feature_change templates.

2. Follow the style guides.

   Note: If writing a new file, a template.py file is provided within the autometa code base to help follow the structure requested by the Autometa team. Please copy and rename this file before you start writing your feature. The template file may be found here, or you may find it within your cloned repository under 'Autometa/docs/template.py'

3. After you submit your pull request, verify that all status checks are passing.

   What if the status checks are failing?

   If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.

While the above must be satisfied, additional prerequisites may be present, depending on the type of pull request being issued (feature change or bug fix). The reviewer(s) may also ask you to complete additional changes before your pull request can finally be accepted.

Style Guides

Git Commit Messages

• Use the present tense ("Add feature" not "Added feature")
• Limit the first line to 72 characters or less
• Reference issues and pull requests liberally after the first line
• Consider starting the commit message with an applicable emoji:
  • 🎨 :art: when improving the format/structure of the code
  • 🐎 :racehorse: when improving performance
  • 📝 :memo: when writing docs
  • 🐧 :penguin: when fixing something on Linux
  • 🍎 :apple: when fixing something on macOS
  • 🐛 :bug: when fixing a bug
  • 🔥 :fire: when removing code or files
  • 💚 :green_heart: when fixing the CI build
  • ✅ :white_check_mark: when adding tests
  • ⬆️ :arrow_up: when upgrading dependencies
  • ⬇️ :arrow_down: when downgrading dependencies
  • 🐍 :snake: for python-related additions/edits
  • 🍏 :green_apple: for nextflow-related additions/edits
  • 🐚 :shell: for bash workflow-related additions/edits

Documentation Style Guide

Documentation is hosted on reathedocs.org which uses sphinx, a python documentation generator. Therefore a common syntax for documenting files within the source code is required. The Autometa team follows numpy syntax to automate as much of the documentation build as possible.

• Numpy documentation style guide
• Sphinx restructured text style guide

Python Style Guide

We have moved all development to using the black formatter and run pre-commit hooks with black such that all of the fuss with formatting according to code specifications can be ignored! When first cloning the repository, you should first install pre-commit and run pre-commit install. This will ensure any commits you make will be formatted appropriately.

Notifying the Team

You may notify the Autometa team corresponding to the respective update/bug by mentioning them in a comment within your issue or pull request.

Note: Please only use @KwanLab/autometa if you receive no response from any of the other teams below.

Team	Area of Development
@KwanLab/autometa-core	Members developing the core functionality
@KwanLab/autometa-website	Members developing the website
@KwanLab/autometa	All Members of the Autometa team