Contributing to 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.
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
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
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 firstname.lastname@example.org.
We encourage community members to contact us at email@example.com prior to contributing a new app in order to avoid potential miscommunications or duplication of efforts.
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 firstname.lastname@example.org. 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.
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
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 email@example.com.
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 firstname.lastname@example.org. 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.
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 email@example.com.
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
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 firstname.lastname@example.org: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
ecoevoappsrepository 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
ecoevoappsrepository. We will communicate with you about any issues that need to be resolved prior to merging, should they arise.