contributing.md

Contributing

Documentation • Getting help • Contributing

---

Table of Contents

• Introduction
• Where can I help?
• Reporting issues
• Requesting features
• Contribution conventions
• Contributing code
• Contributing documentation
• Test locally

Introduction

Integration Roadmaps have separate tracks that roadmap necessary (and optional) tasks for Resource Providers to accomplish to integrate into the ACCESS ecosystem.

Our Code of Conduct can be found here. For a general introduction, please see the general introduction.

Where can I help?

To get help please see Getting help.

To provide help, we welcome any kind of help including reporting issues, requesting features, and making documentation contributions following the contribution conventions.

Reporting issues

• Search ACCESS integration roadmaps issues tracker in case your issue was already reported.

TODO mention recommended wording, tags, etc

Requesting feature(s)

Contribution conventions

This repository follows the GitHub flow model as a workflow for collaborating and uses CommonMark as the markdown model for documentation.

It is strongly recommended to test changes locally before submitting a pull request.

Branch naming recommendation

When creating a branch, adding the author's name and then a descriptive branch name of the intended commits can be helpful to categorize and track changes:

user/clear-purpose-of-proposed-changes (e.g. mollycule/add-readthedocs-contribute-doc)

Contributing code

In order to contribute to the Integration Roadmaps documentation, you must first be part of the access-ci-org organization.

GitHub -> Read the Docs workflow

In order to contribute to the workflow between the GitHub repo and Read the Docs, you must request to become a maintainer by creating an issue stating your:

• full name
• GitHub account name
• ACCESS affilliation

Contributing documentation

For Integration Roadmaps documentation

To contribute to Integration Roadmap tasks, here are the recommended steps (following the Github flow model):

• create a branch following the branch naming recommendation
• create, edit, delete, or rename files inside your branch
• IMPORTANT: test your changes locally for any syntax, styling, or broken link errors
• create a pull request for peer review

Test locally

# Create a Python virtual environment and activate it
virtualenv venv
source venv/bin/activate

# Go to docs/ directory
cd docs/

# Install Python dependencies
pip install -r requirements.txt

# Build documentation
make html

Then, you can see the output in your web browser at Integration_Roadmaps/docs/build/html/index.html.