|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## How to Contribute |
| 4 | + |
| 5 | +The UA Libraries Scholarly API Cookbook is an open source resource. Contributions from students, faculty, staff, and the broader community are welcome. |
| 6 | + |
| 7 | +### Reporting Errors or Suggesting Improvements |
| 8 | + |
| 9 | +If you find an error, outdated code, broken link, or unclear explanation, please open an issue in the [GitHub Issues](https://github.com/UA-Libraries-Research-Data-Services/UALIB_ScholarlyAPI_Cookbook/issues). |
| 10 | + |
| 11 | +When creating an issue, it is helpful to include: |
| 12 | + |
| 13 | +- A link to the specific tutorial page |
| 14 | +- A description of the issue |
| 15 | +- Any relevant error messages |
| 16 | +- Suggested corrections (if available) |
| 17 | + |
| 18 | +We review issues regularly and will respond as soon as possible. |
| 19 | + |
| 20 | +### Requesting New APIs or Tutorials |
| 21 | + |
| 22 | +If you would like to see support for a specific scholarly API, please open a GitHub issue describing: |
| 23 | + |
| 24 | +- The name of the API |
| 25 | +- A link to its official documentation |
| 26 | +- Why it would be useful for research or teaching |
| 27 | +- Whether the API is open access or requires institutional credentials |
| 28 | + |
| 29 | +### Submitting Code Contributions |
| 30 | + |
| 31 | +Before submitting a pull request, please open an issue to discuss proposed changes. This helps ensure alignment with project goals and avoids duplicated work. |
| 32 | + |
| 33 | +For tutorial contributions: |
| 34 | + |
| 35 | +- Follow existing Python or R tutorial structure and formatting, particularly as it relates to licensing, external packages, and API authentication. |
| 36 | +- Ensure all code runs without errors. |
| 37 | +- Include clear explanations and comments. |
| 38 | +- Avoid hard-coded credentials or private API keys. |
| 39 | + |
| 40 | +All contributions are reviewed for accuracy, clarity, reproducibility, and consistency with project standards. |
| 41 | + |
| 42 | +## Project Scope |
| 43 | + |
| 44 | +As of 2025, the Cookbook focuses on maintaining and standardizing Python and R tutorials. Other language have been archived and are no longer actively maintained. |
| 45 | + |
| 46 | +### Project Infrastructure |
| 47 | + |
| 48 | +The Scholarly API Cookbook is built using the following tools: |
| 49 | + |
| 50 | +- Python tutorials are written in [Jupyter Notebooks](https://jupyter.org/). |
| 51 | +- R tutorials are written in RMarkdown and exported to Markdown. |
| 52 | +- Narrative content is written in [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). |
| 53 | +- The site is compiled using [Jupyter Book](https://jupyterbook.org/). |
| 54 | +- An automated GitHub workflow builds the site and deploys it using [GitHub Actions](https://docs.github.com/en/actions). |
| 55 | + |
| 56 | +Contributors should ensure that all notebooks and Markdown files build successfully before submitting changes. |
| 57 | + |
| 58 | +## Questions |
| 59 | + |
| 60 | +If you are unsure whether an idea fits the project scope, please open an issue to start a discussion. |
0 commit comments