First of all, we are really happy that you are reading this, because this means that you are considering contributing to our repositories, which is awesome. 🎉👍
The following is a set of guidelines for contributing to repositories which are hosted in the CSBiology Organization on GitHub. These guidelines are subject to changes, and therefore should not be thought about as strict rules. Feel free to suggest changes with a pull request to this file
If you just want to know how to start contributing without reading all of this stuff, go here for a quickstart guide, or here for more indepth information
Repository structure and scope
This project and everyone participating in it is governed by the CSBiology Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to info@biofsharp.com.
Members of the CSBiology organization are group members of the Computational Systems Biology workgroup at the Technical University Kaiserslautern, headed by Jun. Prof. Dr. Timo Mühlhaus
The main focus of our group is the application and development of computational methods to process and integrate quantitative biological data from modern high-throughput measurements to gain novel insights into plant acclimation responses. Therefore, we want to drive theory and technology forward with a combination of biological science, applied informatics and statistical approaches.
However, the scope of our projects is not limited to our particular research topic.
We mainly develop in the F# programming language, which we see as perfectly suited for large scale data analysis. All of our repositories are the result of our active research, which we make publicly available by going open source.
One part of our research activity is data analysis. Therefore, projects that are used in that process may be subject to a burst of changes in a brief period of time. This is the reason why we work on our projects in two branches:
-
developerbranch: As the name suggests, this is where the bulk development work is done. All changes and pull request should target this branch instead of themasterbranch. Due to the speed of changes to the codebase, anugetbranch is used to host prerelease packages as a git source. We mainly use these packages because such frequent updates to nuget.org take to much time and would slow down research. -
'master' branch: This is the place for stable releases. The
developerbranch will be merged into this branch on a semi-regular basis. The codebase used for publishing release packages on nuget.org can be found here
Here is a brief overview of our main projects (also available here) :
| Project | Description | Docs |
|---|---|---|
| BioFSharp | Provides data structures for common biological entities like amino acids and nucleotides, as well as various algorithms suited for computational biology. Additionally, it contains a steadily growing amount of parsers for biological file formats | https://csbiology.github.io/BioFSharp/ |
| FSharp.Stats | Statistics, Linear Algebra, Machine learning, Optimization and Fitting. Everything needed for (statistical) data analysis belongs here. | https://csbiology.github.io/FSharp.Stats/ |
| FSharp.Plotly | Implements charting suitable for use from F# scripting using plotly.js for all kinds of data visualization | https://muehlhaus.github.io/FSharp.Plotly/ |
| FSharpGephiStreamer | F# functions for streaming graph data to the graph visualization software gephi. Helpful for all kinds of network analysis. | https://csbiology.github.io/FSharpGephiStreamer |
| FSharp.FGL | Functional graph library based on the Hekate graph library | https://csbiology.github.io/FSharp.FGL |
| FSharpAux | Auxiliary functions and extensions for F#. Used in all of our projects to extend F# core functionalities for our needs. | https://csbiology.github.io/FSharpAux |
| Label | Description |
|---|---|
| bug | Confirmed bugs or reports that are very likely to be bugs |
| duplicate | Issues which are duplicates of other issues, i.e. they have been reported before. |
| documentation | Issues concerned with the docs of the project |
| FeatureRequest | The name says it all. |
| invalid | Issues which aren't valid (e.g. user errors). |
| priority-* | low, medium, or high. high means that the CSBiology core team is actively working on this issue |
| project-* | Signals the respective subproject this issue is about |
| question | Questions more than bug reports or feature requests (e.g. how do I do X). |
| up-for-grabs | Issues with this label show up on https://up-for-grabs.net if the respective project is registered there. Marks good issues for contributig to the project. |
| wontfix | The CSBiology core team has decided not to fix these issues for now, either because they're working as intended or for some other reason. |
Our F# projects use the ProjectScaffold layout. To build our projects, you will need .NET Core SDK and an installation of FAKE5 CLI.
All projects have at least the following build targets:
| Target | Description | Command Line Arguments |
|---|---|---|
| Build | Builds the binaries and docs | fake build |
| ReleaseLocal | Uses Build. Afterwards creates a folder structure so you can see the docs with proper style and relative paths in temp/localDocs. Use this to test documentation. | fake build --target releaselocal |
This section guides you through submitting a bug report for our repositories. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. Fill out the required template, the information it asks for helps us resolve issues faster.
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.
- Determine which repository the problem should be reported in.
- Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.
Bugs are tracked as GitHub issues. After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template.
Explain the problem and include additional details to help maintainers reproduce the problem:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps which reproduce the problem in as many details as possible. When listing steps, don't just say what you did, but explain how you did it.
- Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use Markdown code blocks.
- Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
- Explain which behavior you expected to see instead and why.
- Include screenshots which show you following the described steps and clearly demonstrate the problem.
- If the problem wasn't triggered by a specific action, describe what you were doing before the problem happened and share more information using the guidelines below.
Provide more context by answering these questions:
- If the problem started happening recently, can you reproduce the problem in an older version of the project? What's the most recent version in which the problem doesn't happen?
- Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
Include details about your configuration and environment:
- What's the name and version of the OS you're using?
- Which version of .NET Core SDK are you using?
- Are you encountering the bug in a virtual machine? If so, which VM software are you using and which operating systems and versions are used for the host and the guest?
This section guides you through submitting a feature request, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Before creating feature requests, please check this list as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please include as many details as possible. Fill in the template, including the steps that you imagine you would take if the feature you're requesting existed.
- Determine which repository the enhancement should be suggested in.
- Perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
Feature requests are tracked as GitHub issues. After you've determined which repository your enhancement suggestion is related to, create an issue on that repository and provide the following information:
- 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. Include copy/pasteable snippets which you use in those examples, as Markdown code blocks.
- Describe the current behavior and explain which behavior you expected to see instead and why.
- Include screenshots which help you demonstrate the steps which the suggestion is related to.
- Explain why this feature would be useful
- Specify the name and version of the OS you're using.
Please follow these steps to have your contribution considered by the maintainers:
- Follow all instructions in the template
- Follow the styleguides
- 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.
- Submit an issue related to the contribution you want to make. Please do not submit pull request that have no corresponding issue.
- Create a fork of the respective project and create a new branch (ideally named after the contribution you want to make)
- Keep your commits granular and concise, so that your commit history is easily trackable by reviewers. See here for basic guidelines about git commit messages
- Group like-changes in one commit, and avoid to combine different types of changes in a single commit.
- Base pull requests on the
developerbranch of the respective project - Fill out the template which will show up when creating a pull request
- Thank you for contributing ❤️
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests liberally after the first line
As most of our members are more or less self-taught programmers, we are not used to obey strict coding conventions. We try to obey the general F# style guide, but there could be exceptions. Suggestions in this field are highly appreciated.
One of our biggest weakness at the moment are unit tests. We will love everyone helping us out on that front.
The docs in our repos are built by the F# Formatting Documentation tools which parse .fsx files in the docsrc/content folder to generate html files. Again, no strict rules here, just a few minor guidelines:
-
If you add or change functionality to a project, please consider adding/changing the respective documentation script. If you dont have time to do that, please comment it on your pull request.
-
Most documentation is written in a tutorial-style manner. If you use external files in your examples, put them into docsrc/content/data.
-
API References are built from triple frontslash comments (
///), please consider adding those above the functions/types/classes you are adding.
This document is adapted from the atom contribution guidelines