Collaborate with PSLab!

Welcome to the PSLab (Pocket Science Lab) collaboration guide. This document will help you get started with contributing to the PSLab repository.

Pocket Science Lab Experiments

One of the best ways to contribute to PSLab is by creating experiments. These experiments help users explore the capabilities of the Pocket Science Lab and learn about various scientific concepts.

Creating an Experiment

  1. Fork the repository

  2. Create and/or edit files using your preferred editor

  3. Follow the structure outlined in tutorials/template.md

File Formats

We primarily use Markdown (.md) for our documentation. However, please note:

  • The main document headlines (typically the first one at the top of the file) should be written in reStructuredText (ReST) format for compatibility with Sphinx documentation.

  • The rest of the content should be in Markdown format.

For convenience, you can use notex, an open-source ReST editor.

Editing Tools

While you can use any text editor of your choice, we recommend using open-source Markdown editors for convenience. Some options include:

  • Visual Studio Code with Markdown extensions

  • Typora

  • MarkText

  • Joplin

These editors provide live previews and other helpful features for writing Markdown.

How to Contribute

Reporting Bugs

  • Before submitting a bug report, please check our issue tracker to see if the bug has already been reported.

  • If you’re unable to find an open issue addressing the problem, open a new one.

  • When you are creating a bug report, please include as many details as possible:

    • Use a clear and descriptive title

    • Describe the exact steps which reproduce the problem

    • Provide specific examples to demonstrate the steps

    • Describe the behavior you observed after following the steps

    • Explain which behavior you expected to see instead and why

    • Include screenshots if possible

    • Include your environment details (OS, browser version, etc.)

Suggesting Enhancements

  • Use a clear and descriptive title for the issue to identify the suggestion.

  • Provide a step-by-step description of the suggested enhancement in as many details as possible.

  • Provide specific examples to demonstrate the steps or point out the part of PSLab where the suggestion is related to.

  • Describe the current behavior and explain which behavior you expected to see instead and why.

  • Explain why this enhancement would be useful to most PSLab users.

  • List some other projects or applications where this enhancement exists, if applicable.

Your First Code Contribution

  • Start with our list of beginner-friendly issues labeled as “good first issue” in our issue tracker.

  • If you’re just getting started with PSLab, consider working on documentation improvements or adding new experiments.

  • Don’t hesitate to ask for help in our community channels if you’re stuck.

Pull Requests

  • Fill in the required template when creating your pull request.

  • Do not include issue numbers in the PR title.

  • Follow our coding standards and style guides.

  • Include appropriate test cases if you’re adding new functionality.

  • Ensure all tests pass before submitting your pull request.

  • Update the documentation, if relevant to your changes.

Submitting Your Contribution

Once you’ve created or edited your files:

  1. Commit your changes to your forked repository

  2. Create a pull request to the main PSLab repository

  3. Wait for review and feedback from the maintainers

Thank you for contributing to PSLab! Your efforts help make science more accessible to everyone.