Contributing to EcoEvoApps • ecoevoapps

We envision EcoEvoApps as a community resource and have developed the project with an explicit focus on enabling contributions from across the EEB community. There are a range of mechanisms by which community members with varying degrees of theoretical, computational, and pedagogical expertise can contribute to this project. This vignette outlines these mechanisms and provides guidelines for how community members can become involved in this project. Beyond the contribution guidelines described here, we expect all individuals contributing to this project in any capacity to adhere to our Contributor Covenant Code of Conduct. Contributors will be acknowledged in the ecoevoapps R package source code and/or on the EcoEvoApps website.

1. Write and contribute a new app

Development of the ecoevoapps R package and EcoEvoApps website takes place collaboratively on GitLab, where we write, review, and deploy new apps. If there is a model or app that you would like to see implemented in EcoEvoApps, you can help the project grow by writing and contributing a new app. The most direct way to do this is to interact directly with the ecoevoapps repository on GitLab. If you are new to using git or GitLab, please see the section Contributing to EcoEvoApps via GitLab for further information about this workflow. If you would like to contribute an app but are unfamiliar with git or GitLab, you can also email us at ecoevoapps@gmail.com.

New apps should aim to satisfy the basic requirements described in the section Review process for contributed apps. In addition to fully functioning apps, we also welcome contributions of code that simulates model dynamics but which has not yet been made into an interactive app. Such code can be used by core developers or other community members as the groundwork for writing a new app, potentially in collaboration with the author of the original code. If you are interested in contributing code in this manner, please email us at ecoevoapps@gmail.com.

We encourage community members to contact us at ecoevoapps@gmail.com prior to contributing a new app in order to avoid potential miscommunications or duplication of efforts.

2. Revise or translate an existing app

Community members can also contribute to EcoEvoApps by revising or translating existing apps. The most direct way to revise or translate an app is to interact directly with the ecoevoapps repository on GitLab. See the section Contributing to EcoEvoApps via GitLab for further information about this workflow. If you are not comfortable working with git or GitLab, you can also email us the revised code or translated text at ecoevoapps@gmail.com. If you have ideas for a revision but are not sure how to implement your idea, or want someone else to implement your idea, please email us or submit a feature request as described in the section Provide feedback or request new apps/features below.

3. Provide feedback or request new apps/features

We greatly value feedback and suggestions from community members on any aspect of EcoEvoApps. If you spot an issue with any of the existing apps, you can submit a bug report using this form or by directly opening an issue in the ecoevoapps repository on GitLab. You can similarly request new features for existing apps or request entirely new apps that you would like to see implemented. You can also directly correspond with us about any issues, suggestions, or requests by emailing us at ecoevoapps@gmail.com.

4. Contribute classroom use cases and activities

To facilitate the adoption of EcoEvoApps in the classroom, we intend to compile and make available to community members resources, use cases, and activities that exemplify how instructors can use these apps in an educational context. If you are an instructor and are willing to share your experience or course materials pertaining to the use of EcoEvoApps in your classes, please get in touch with us at ecoevoapps@gmail.com. We also welcome testimonials and feedback from students who have interacted with EcoEvoApps in one or more of their classes. Further details regarding this effort are forthcoming.

Review process for contributed apps

Newly contributed apps or modifications to existing apps will be reviewed following a standard procedure prior to inclusion in the ecoevoapps R package or EcoEvoApps website. In this section we describe the basic requirements for contributed apps and provide an overview of the app review process.

Basic requirements for all apps:

Title of the app
Short description of the model or app
Equations or diagrams representing the model (when applicable)
Definitions of all variables and parameters
At least one user-defined input
At least one reactive figure complete with labels and legends
References (when applicable)

New apps will receive following designations based on the degree to which they have been tested and reviewed:

Beta: Newly contributed or modified apps will first be evaluated by one or more core developers for whether they satisfy all of the basic app requirements listed above. Apps that have been confirmed to satisfy these criteria will be marked as beta and will be deployed on the EcoEvoApps website.

Reviewed: Recently contributed or modified apps in the beta stage will next be reviewed by one or more app reviewers, who will check whether the apps can be run without runtime errors (e.g. all figures update in response to user inputs, no error messages, no unexpectedly long delays, etc.). Apps that have passed this basic review process will be marked as reviewed on the EcoEvoApps website.

Stable: Additionally, reviewers who are familiar with the biological context and expected behavior of the apps can review the description text, equations or diagrams, and model behavior (e.g. bifurcation points, equilibria, etc.) to confirm that the apps are not only fully functional but also biologically accurate. Apps that have passed this advanced review process will be marked as stable on the EcoEvoApps website, and can be incorporated into the ecoevoapps R package.

If you would like to request an exception to the standard review process outlined above, please email us at ecoevoapps@gmail.com.

Contributing to EcoEvoApps via GitLab

The most direct way to contribute a new app or to revise an existing app is to directly work with the ecoevoapps repository on GitLab. In this section we describe the general workflow for contributing to EcoEvoApps via GitLab. Note that this is not meant to be a comprehensive tutorial for git and GitLab, but rather is a rough outline of the general process of contributing to this project via GitLab.

Fork the ecoevoapps repository on GitLab. This creates a personal copy of the repository.
Clone the forked repository to a desired directory on your device. This allows you to modify your copy of the repository locally.

Clone with SSH:
```
git clone git@gitlab.com:USERNAME/ecoevoapps.git
```
Clone with HTTPS:
```
git clone https://gitlab.com/USERNAME/ecoevoapps.git
```
Once you are ready to start working on a new app or feature, create a feature branch in your fork with a descriptive title. This allows you to make modifications to your fork without directly modifying the master branch.
```
git checkout -b FEATUREBRANCH
```
Now you can work on developing your new app or feature on your feature branch, staging, committing, and pushing any notable changes to GitLab as you go. Remember to keep in mind the review criteria described in the section Review process for contributed apps when writing or revising an app.
```
git add -A
git commit -m "COMMIT MESSAGE"
git push origin FEATUREBRANCH
```
Once you are ready to submit your new app or feature, navigate to your forked repository on GitLab and create a merge request. Make sure to select the feature branch of your fork as the source branch and the master branch of the original ecoevoapps repository as the target branch. Add a descriptive title to your merge request and describe the additions or changes you have made in the description box, then submit the merge request.
Your merge request will be reviewed by one or more of the core developers. Once the merge request and the submitted app or feature has been satisfactorily reviewed (see section Review process for contributed apps), the merge request will be accepted and your contributions will be incorporated into the original ecoevoapps repository. We will communicate with you about any issues that need to be resolved prior to merging, should they arise.