Skip to content

Commit 42d56c5

Browse files
sayalaruanosayalaruano
authored
📝 Upate CONTRIBUTING.md file and create PR template (#163)
* 📝 Docs(README.md): update license badge * 📝 Docs(CONTRIBUTING.md): update file based on the latest changes on vuecore and acore contrib files * 🧑‍💻 Docs(.github/PULL_REQUEST_TEMPLATE.md): Add general PR template * ✏️ Docs(CONTRIBUTING.md): fix incorrect links * ✏️ Docs(CONTRIBUTING.md): fix spacing
1 parent f434add commit 42d56c5

File tree

3 files changed

+220
-29
lines changed

3 files changed

+220
-29
lines changed

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<!--
2+
Please complete the following sections when you submit your pull request. Note that text within html comment tags will not be rendered.
3+
-->
4+
### Summary
5+
6+
<!-- Describe the problem you're trying to fix in this pull request. Please reference any related issue and use fixes/close to automatically close them, if pertinent. For example: "Fixes #58", or "Addresses (but does not close) #238". -->
7+
8+
Fixes #<NUM>
9+
10+
...
11+
12+
### List of changes proposed in this PR (pull-request)
13+
14+
<!-- We suggest using bullets (indicated by * or -) and filled checkboxes [x] here -->
15+
16+
* ...
17+
* ...

‎CONTRIBUTING.md‎

Lines changed: 201 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,245 @@
11
# Contributing to VueGen
22

33
[VueGen][vuegen-repo] is an open source project, and we welcome contributions of all
4-
kinds via GitHub issues and pull requests: correct or improve our [documentation][vuegen-docs], report or fix bugs, propose changes, and implement new features. Please follow
5-
these guidelines to make sure that your contribution is easily integrated into the project.
4+
kinds via **GitHub issues** and **pull requests**: correct or improve our
5+
[documentation][vuegen-docs], report or fix bugs, propose changes, and implement new
6+
features. Please follow these guidelines to make sure that your contribution is easily
7+
integrated into the project.
68

7-
## 1. Contributor Agreement
9+
## Contributor Agreement
810

911
By contributing, you agree that we may redistribute your work under [our
10-
license](LICENSE). In exchange, we will address your issues and/or assess
12+
license](LICENSE.md). In exchange, we will address your issues and/or assess
1113
your change proposal as promptly as we can, and help you become a member of our
1214
community.
1315

14-
## 2. What to Contribute
16+
## What to Contribute?
1517

16-
The easiest way to get started is by reporting an issue that needs to be fixed,
17-
such as a bug in the code, unclear explanations, conceptual errors, or other details.
18-
You can also contribute by proposing new features or modules, improving existing
19-
functionality, or suggesting other ideas that might be useful. If you’re looking for
20-
inspiration, please check the [list of open issues][issues] in this repository.
18+
The easiest way to get started is by **reporting an issue** that needs to be fixed,
19+
such as a bug in the code, unclear explanations, conceptual errors, or other details.
20+
If you are familiar with Python, Git,, and GitHub, you can **fix the bug** yourself
21+
and submit a **pull request (PR)** with your changes, as described below.
22+
23+
You can also contribute by **fixing existing bugs** tagged with the `bug` and
24+
`help wanted` labels in the [list of open issues][issues] of the repository. There are
25+
**new features and imporvements** tagged with `enhancement` and `help wanted` as well, so
26+
feel free to start a discussion if you would like to work on one of those. If you come up with
27+
any **ideas for new features or improvements** that are not yet reported, we are also happy to hear about them.
2128

2229
Feedback from beginners is especially valuable, as experienced users may overlook how
2330
challenging certain aspects of the software can be for newcomers. Therefore, we encourage
24-
you to share any suggestions or observations you have about this project.
31+
you to share any suggestions or observations you have.
2532

26-
## 3. How to Contribute
33+
## How to Contribute?
2734

2835
Here are the ways you can submit your suggestions and contribute to the project:
2936

3037
### 1. Reporting Issues or Suggesting Improvements
3138

32-
If you have a [GitHub][github] account (or are willing to [open one][github-join]) but are unfamiliar with Git, you can report bugs or suggest improvements by [creating an issue][new-issue]. This GitHub feature allows for discussion threads on reported issues and proposed enhancements.
39+
If you have a [GitHub][github] account (or are willing to [open one][github-join]) but are unfamiliar with
40+
Git, you can report bugs or suggest improvements by [creating an issue][new-issue]. This GitHub feature allows
41+
for discussion threads on reported issues and proposed enhancements.
42+
43+
When reporting an issue, please provide as much relevant information as possible, including:
44+
45+
* A clear and descriptive title
46+
* A detailed description of the problem or suggestion
47+
* Steps to reproduce the issue (if applicable)
48+
* Any relevant screenshots or error messages
49+
* Your operating system, software version, and additonal details about your local setup that might be helpful in troubleshooting
50+
51+
> [!TIP]
52+
> This guide from the [GitHub Docs][github-docs] provides useful tips on [how to write an issue][issue-github-guide].
3353
3454
### 2. Submitting Changes via Pull Requests
3555

36-
If you are comfortable using Git and would like to add or modify a functionality, you can submit a **pull request (PR)**. Instructions on how to contribute this way are provided in the next section.
56+
If you are comfortable using Git/GitHub and would like to add or modify a functionality, you can submit a **PR**.
57+
You may want to look at [How to Contribute to an Open Source Project on GitHub][how-contribute].
58+
In brief, we use [GitHub flow][github-flow] to manage changes:
59+
60+
> [!TIP]
61+
> Consider using an IDE (e.g., [VSCode][vscode]) or a GUI client (e.g., [GitHub Desktop][github-desktop]) to help
62+
> you with some of the common steps described below.
63+
64+
1. Fork the [vuegen][vuegen-repo] repo on GitHub.
65+
2. Clone your fork locally. Replace `yourusername` with your GitHub username.
66+
67+
```bash
68+
git clone https://github.com/yourusername/vuegen.git
69+
```
70+
71+
3. Install your local copy into a virtual environment. Assuming you have Python available
72+
on your system, this can be done using `venv`. Alternatives are `conda`, `uv`, or `poetry`
73+
to create and manage virtual environments.
74+
75+
```bash
76+
cd vuegen/
77+
python -m venv .env
78+
source .env/bin/activate
79+
pip install -e .[dev]
80+
```
81+
82+
4. Create a new branch in your desktop copy of this repository for each significant change.
3783

38-
### 3. Providing Feedback via Email
84+
```bash
85+
git checkout -b name-of-your-new-branch
86+
```
3987

40-
If you don’t have a GitHub account and are unfamiliar with Git, you can send feedback via email to [asaru@dtu.dk][contact]. However, using GitHub is preferred, as it allows us to respond more quickly and track discussions openly.
88+
5. When you're done making changes, check that your changes are formatted and pass `black` and
89+
`ruff` checks (some changes ruff can automatically fix for you, if you pass the `--fix` flag).
90+
Also, run the `tests` to make sure everything is working as expected:
4191

42-
> [!NOTE]
43-
> The documentation for [Git][git-docs] and [GitHub][github-docs] are easy to follow, and you can learn the basics using their official guides.
92+
```bash
93+
black .
94+
ruff check src
95+
pytest .
96+
```
4497

45-
## 4. Creating a Pull Request
98+
6. Commit the changea in that branch.
4699

47-
If you choose to contribute via GitHub, you may want to look at [How to Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we use [GitHub flow][github-flow] to manage changes:
100+
```bash
101+
git add .
102+
git commit -m "Your detailed description of your changes."
103+
```
48104

49-
1. Create a new branch in your desktop copy of this repository for each significant change.
50-
2. Commit the change in that branch.
51-
3. Push that branch to your fork of this repository on GitHub.
52-
4. Submit a pull request from that branch to the [upstream repository][vuegen-repo].
53-
5. If you receive feedback, make changes on your desktop and push to your branch on GitHub: the
105+
7. Push that branch to your fork of this repository on GitHub.
106+
107+
```bash
108+
git push origin name-of-your-new-branch
109+
```
110+
111+
8. Submit a pull request from that branch to the [upstream repository][vuegen-repo] via GitHub.
112+
See the **PR General Guidelines** below for more details.
113+
9. If you receive feedback, make changes on your desktop and push to your branch on GitHub: the
54114
pull request will update automatically.
55115

56-
## 5. Credits
116+
> [!TIP]
117+
> The documentation for [Git][git-docs] and [GitHub][github-docs] are easy to follow, and you can learn the
118+
> basics using their official guides.
119+
120+
#### PR General Guidelines
121+
122+
We have a general [PR template][general-pr-template] that is loaded autmatically when you open
123+
a new PR. Before you submit a PR, check that it meets these guidelines:
124+
125+
1. The pull request should include tests.
126+
2. If the pull request adds functionality, the docs should be updated. Put
127+
your new functionality into a function with a docstring.
128+
3. The pull request should pass the workflows on GitHub.
129+
130+
## Code & Documentation Standards
131+
132+
To maintain consistency across the codebase, please adhere to the following standards when contributing:
133+
134+
* **Docstrings:** Follow the [NumPy docstring style][numpy-docstring-guide]. Include examples where relevant.
135+
* **Type Hints:** Use Python type hints for function signatures and variable annotations (**PEP 484**).
136+
* **Code Formatting:** Use `black` for code formatting and `ruff` for linting (as mentioned in the PR guidelines).
137+
* **Naming Conventions:** Follow **PEP8** for naming (e.g., snake_case for variables/functions, CamelCase for classes).
138+
139+
Here is an example of a simple function with a proper docstring and type hints:
140+
141+
```python
142+
def calculate_average(values: List[float]) -> float:
143+
"""
144+
Calculate the average of a list of numerical values.
57145
58-
This contribution guide was modified under the [Creative Commons Attribution 4.0 International License][ccby] from the [Software Carpentry guides][soft-cp-guides].
146+
Parameters
147+
----------
148+
values : List[float]
149+
List of numerical values to average.
150+
151+
Returns
152+
-------
153+
float
154+
The arithmetic mean of the input values.
155+
156+
Examples
157+
--------
158+
>>> calculate_average([1.0, 2.0, 3.0, 4.0])
159+
2.5
160+
"""
161+
return sum(values) / len(values)
162+
```
163+
164+
## Test Guidelines
165+
166+
We encourage comprehensive testing to maintain code quality, so all contributions should include
167+
appropriate tests that verify functionality. We use `pytest` as our testing framework. Here are some considerations:
168+
169+
* **Structure:** Place tests in the tests/ directory, mirroring the source structure.
170+
* **Coverage:** Aim for high test coverage, especially for new features or bug fixes. Try to cover typical use cases as well as edge cases.
171+
* **Naming:** Use descriptive test function names that indicate what is being tested.
172+
* **Docstrings:** Include docstrings in your test functions to explain their purpose, following the previous docstring guidelines.
173+
* **Isolation:** Each test should be independent and not rely on other tests.
174+
* **Local Execution:** Ensure that tests can be run locally using `pytest` before submitting a PR.
175+
176+
Here is an example of a test script for the `calculate_average` function:
177+
178+
```python
179+
import pytest
180+
from vuegen.utils import calculate_average
181+
182+
def test_calculate_average_basic():
183+
"""Test basic average calculation with positive numbers."""
184+
result = calculate_average([1.0, 2.0, 3.0, 4.0])
185+
assert result == 2.5
186+
187+
def test_calculate_average_single_value():
188+
"""Test average calculation with a single value."""
189+
result = calculate_average([5.0])
190+
assert result == 5.0
191+
192+
def test_calculate_average_empty_list():
193+
"""Test average calculation with empty list raises appropriate error."""
194+
with pytest.raises(ZeroDivisionError):
195+
calculate_average([])
196+
```
197+
198+
Run the following command in the root directory to execute the tests locally:
199+
200+
```bash
201+
pytest .
202+
```
203+
204+
It's possible to run specific test files or functions by providing their paths.
205+
See the [pytest documentation][pytest-docs] for more details.
206+
207+
## Deployment
208+
209+
We created a [CI/CD worflow][cicd-workflow] using **GitHub Actions** to automatically deploy the Python package to
210+
[PyP][vuegen-pypi] when a new release is created. To create a new release, make sure all changed are merged into the `main` branch,
211+
then go to the [Releases section][releases-vuegen] of the GitHub repository and click on **Draft a new release**. Fill in the
212+
release title and description, then click on **Publish release**. This will trigger the GitHub Actions workflow to build and deploy the package to PyPI.
213+
214+
Also, we have a GitHub Action that automatically deploys the documentation to [Read the Docs][vuegen-docs] in
215+
every push to a branch or when a PR is merged into `main`.
216+
217+
## Credits
218+
219+
This contribution guide was modified under the [Creative Commons Attribution 4.0 International License][ccby] from the [Software Carpentry guides][soft-cp-guides], [vuecore][vuecore-repo], and
220+
[acore][acore-repo] projects.
59221

60222
[vuegen-repo]: https://github.com/Multiomics-Analytics-Group/vuegen
61223
[vuegen-docs]: https://vuegen.readthedocs.io/
62224
[issues]: https://github.com/Multiomics-Analytics-Group/vuegen/issues
63225
[new-issue]: https://github.com/Multiomics-Analytics-Group/vuegen/issues/new
64226
[github]: https://github.com
65227
[github-join]: https://github.com/join
66-
[contact]: mailto:asaru@dtu.dk
67228
[git-docs]: https://git-scm.com/doc
68229
[github-docs]: https://guides.github.com/
230+
[issue-github-guide]: https://docs.github.com/en/issues/tracking-your-work-with-issues/learning-about-issues/quickstart
69231
[how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
70232
[github-flow]: https://guides.github.com/introduction/flow/
233+
[vscode]: https://code.visualstudio.com/
234+
[github-desktop]: https://github.com/apps/desktop
235+
[general-pr-template]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/.github/PULL_REQUEST_TEMPLATE.md
236+
[numpy-docstring-guide]: https://numpydoc.readthedocs.io/en/latest/format.html
237+
[pytest-docs]: https://docs.pytest.org/en/stable
238+
[cicd-workflow]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/.github/workflows/cdci.yml
239+
[vuegen-pypi]: https://pypi.org/project/vuegen/
240+
[releases-vuegen]: https://github.com/Multiomics-Analytics-Group/vuegen/releases
71241
[soft-cp-guides]: https://software-carpentry.org/lessons/
72242
[ccby]: https://creativecommons.org/licenses/by/4.0/
243+
[vuecore-repo]: https://github.com/Multiomics-Analytics-Group/vuecore
244+
[acore-repo]: https://github.com/Multiomics-Analytics-Group/acore
245+

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
| Information | Links |
88
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9-
| **Package** | [![PyPI Latest Release](https://img.shields.io/pypi/v/vuegen.svg)][vuegen-pypi] [![Conda Latest Release](https://img.shields.io/conda/v/bioconda/vuegen.svg)][vuegen-conda] [![Supported versions](https://img.shields.io/pypi/pyversions/vuegen.svg)][vuegen-pypi] [![Docker Repository on Quay](https://quay.io/repository/dtu_biosustain_dsp/vuegen/status "Docker Repository on Quay")][vuegen-docker-quay] [![License](https://img.shields.io/github/license/Multiomics-Analytics-Group/vuegen)][vuegen-license]|
9+
| **Package** | [![PyPI Latest Release](https://img.shields.io/pypi/v/vuegen.svg)][vuegen-pypi] [![Conda Latest Release](https://img.shields.io/conda/v/bioconda/vuegen.svg)][vuegen-conda] [![Supported versions](https://img.shields.io/pypi/pyversions/vuegen.svg)][vuegen-pypi] [![Docker Repository on Quay](https://quay.io/repository/dtu_biosustain_dsp/vuegen/status "Docker Repository on Quay")][vuegen-docker-quay] [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)][mit-license]|
1010
| **Documentation** | [![View - Documentation](https://img.shields.io/badge/view-Documentation-blue?style=flat)][vuegen-docs] [![made-with-sphinx-doc](https://img.shields.io/badge/Made%20with-Sphinx-1f425f.svg)](https://www.sphinx-doc.org/) ![Docs](https://readthedocs.org/projects/vuegen/badge/?style=flat) [![CC BY 4.0][cc-by-shield]][vuegen-license]|
1111
| **Build** | [![CI](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/cdci.yml/badge.svg)][ci-gh-action] [![Docs](https://github.com/Multiomics-Analytics-Group/vuegen/actions/workflows/docs.yml/badge.svg)][ci-docs] |
1212
| **Examples** | [![HTML5](https://img.shields.io/badge/html5-%23E34F26.svg?style=for-the-badge&logo=html5&logoColor=white)][emp-html-demo] [![Streamlit](https://img.shields.io/badge/Streamlit-%23FE4B4B.svg?style=for-the-badge&logo=streamlit&logoColor=white)][emp-st-demo] |
@@ -450,6 +450,7 @@ We appreciate your feedback! If you have any comments, suggestions, or run into
450450
[vuegen-docker-quay]: https://quay.io/repository/dtu_biosustain_dsp/vuegen
451451
[docker-folder]: https://github.com/Multiomics-Analytics-Group/nf-vuegen/tree/main/Docker
452452
[vuegen-license]: https://github.com/Multiomics-Analytics-Group/vuegen/blob/main/LICENSE.md
453+
[mit-license]: https://opensource.org/licenses/MIT
453454
[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg
454455
[vuegen-class-diag-att]: https://raw.githubusercontent.com/Multiomics-Analytics-Group/vuegen/main/docs/images/vuegen_classdiagram_withattmeth.pdf
455456
[vuegen-docs]: https://vuegen.readthedocs.io/

0 commit comments

Comments
 (0)