CONTRIBUTING.md

Introduction

Yo, what up! if you're reading this then I'm super psyched because that means that you're thinking about contributing to Poly! Thanks so much for your time and consideration. It's rad people like you that make Poly such a cool computational synthetic biology tool.

I wrote this contributor's guide to help newcomers feel welcome. Getting started with a new project can be complicated and I wanted to make it as easy as possible for you to contribute and as easy as possible for me to help.

Currently any sincere pull request is a good request. Poly is still in pre-release so there are so many way to contribute! Here's a list of ideas but feel free to suggest anything I may have forgotten to include.

• Feature requests - especially cool new algorithms with citations.
• Devops features. Github action bots, linters, deployment, etc.
• Unit and integration tests.
• Writing, editing, and translating tutorials, documentation, or blog posts.
• Auditing for accessibility.
• Bug reports.
• Bug triaging.
• Community management.
• Art! Dreams! Your excellence!
• Code that can be pulled into Poly itself.

Contributor guidelines

Excellence, and the contributor's code of conduct

First up, most importantly we have a contributor's code of conduct. For some reason the internet is a dehumanizing experience and it's easy to forget that aside from the bots we're all humans on this thing. Approach each other with kindness. Please read our contributor's code of conduct and when in doubt just remember our one true rule as once spoken by the ever so wise duo of Bill and Ted.

Bill: Be excellent, ... to each other, ...

Ted: and party on, dudes! [sic]

Do-ocracy

Poly runs on do-ocracy. Do-ocracy is a simple concept. If you don't like something you don't need permission to fix it, you can just go ahead and fix it! If you actually want to merge your fix, or contribute in someway that benefits everybody, it'd really, really, really help if you got some light consensus from the rest of the Poly development community but hey, if you really need to do something then you just gotta do it! Just don't expect me to merge it if it doesn't meet our technical criteria or isn't quite right for Poly.

Technical requirements

Part of what makes Poly so special is that we have standards. DNA is already spaghetti code on its own and we just don't need to add to that.

All successfully merged pull requests must meet the following criteria:

• All current tests must pass.

• At least one new test must be written to prove that the merged feature works correctly.

• At least one new example test must be written to demonstrate the merged feature in our docs.

• Build tests must pass for all currently supported systems and package managers. Linux, Mac OSX, Windows, etc.

• Code must be clean, readable, and commented. How you do that is up to you!

• The PR template, which covers most of these points, should be filled out.

Don't worry if you submit a pull request and all the tests break and the code is not readable. We won't merge it just yet and then you can get some feedback about what needs to be changed before we do!

Be welcoming

As one final guideline please be welcoming to newcomers and encourage new contributors from all walks of life. I want Poly to be for everyone and that includes you and people who don't look, sound, or act like you!

Your first contribution

Unsure where to begin contributing to Poly? You can start by looking through these beginner and help-wanted issues:

Good first issues - issues which are good for first time contributors.

Help wanted issues - issues which should be a bit more involved than beginner issues.

Feature requests - before requesting a new feature search through previous feature requests to see if it's already been requested. If not then feel free to submit a request and tag it with the enhancement tag!

Taking issues

To assign an issue to yourself, simply comment .take on it and it will be assigned to you!

Working on your first Pull Request?

You can learn how from this free series, How to Contribute to an Open Source Project on GitHub.

You can also check out these tutorials.

At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸

Getting started

For something that is bigger than a one or two line fix:

1. Create your own fork of the code.
2. Make a branch in your fork
3. Do the changes in your fork's branch.
4. Send a pull request.

Virtual Environments and Development Containers

In order to simplify the development experience, and environment setup, the poly Github repository comes packaged to support Github CodeSpaces and VSCode Development Containers. Github CodeSpaces will give you ability to spin up a Github hosted instance of Ubuntu that would allow you run, test, develop poly from the browser. VSCode Development Containers in turn will allow your installation of VSCode to spin up a docker instance of Ubuntu on your computer and automatically mount your code onto it so that you continue developing on this docker instance that has all the required development environment setup.

Recommended Plugins

Whether you're a beginner with Go or you're an experienced developer, You should see the suggestions popup automatically when you goto the Plugins tab in VSCode. Using these plugins can help accelerate the development experience and also allow you to work more collaboratively with other poly developers.

How to report a bug

Security disclosures

If you find a security vulnerability, do NOT open an issue. Instead, email poly-collaborators@googlegroups.com with a description of the vulnerability and we will get in contact with you ASAP.

In order to determine whether you are dealing with a security issue, ask yourself these two questions:

• Can I access something that's not mine, or something I shouldn't have access to?
• Can I disable something for other people?

If the answer to either of those two questions are "yes", then you're probably dealing with a security issue. Note that even if you answer "no" to both questions, you may still be dealing with a security issue, so if you're unsure, shoot an email to poly.maintainers@bebop.bio.

Non-security related bugs

For non-security bug reports please submit it using this template!

How to suggest a feature or enhancement

If you want to suggest a feature it's as easy as filling out this issue template, but before you do please check to see if it's already been suggested!

How to add a recommended VSCode Plugin

Poly comes with a set of recommended plugins for VSCode. If you have suggestions that will simplify life for the poly dev community, consider doing a pull-request after modifying .vscode/extensions.json.

Build and Release Pipelines

just Build System

We use just as a task runner. See their README for install instructions. To see the available recipes, execute just list in the root of the repository.

Normal Releases

This project adheres to Semantic Versioning, which looks like so: vMAJOR.MINOR.PATCH. We also keep a changelog in CHANGELOG.md. Major versions indicate breaking changes to the API, minor versions indicate backwards-compatible additions to the API, and patch versions indicate bugfixes.

Cutting a Release

NOTE: Only contributors with write access to the repository can do this.

To cut a release, check out the main branch, merge any desired changes, and then run just cut-release <version> (without the v before the version number). This will perform the following actions locally:

1. Lint and test the codebase
2. Bump the version in the changelog and commit it
3. git tag the commit as v<version>

Afterward, simply run git push and git push <remote> v<version> to upload the new commit and tag to the repository, and GitHub Actions will automatically make a release!

Nightly Releases

poly features automatic nightly releases via GitHub Actions, located here. These will reflect the status of the main branch as of 0800UTC/0300EST.

Issue management

As poly grows, we will see more and more issues added to our GitHub. This will require us to be disciplined about properly labeling issues for easier discoverability and task assignment. Issues will also be tracked in the Projects section of the repository.

Triaging new issues

All new issues will be marked with the needs-triage label, which should promptly be replaced with the following:

• An issue type label (devops, bug, ux, question, proposal, enhancement, documentation)
• A difficulty/effort label (easy, intermediate, hard)
• A priority label (high priority, normal priority, low priority)
• OPTIONAL: help wanted or good first issue where appropriate

Stale issues

After 2 months of no activity, issues will be marked with the stale label. We should periodically sort through stale issues and either close them or assign them.

In closing

Thanks for reading and I'm super psyched to see what you'll do with Poly!