Skip to content

Commit

Permalink
docs: Improve the contributing guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@xmnlab
xmnlab committed Feb 29, 2024
1 parent 4373c42 commit 2693e70
Show file tree
Hide file tree
Showing 3 changed files with 234 additions and 102 deletions.
2 changes: 2 additions & 0 deletions .prettierignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
.makim.yaml
docs/changelog.md
6 changes: 6 additions & 0 deletions .prettierrc.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
overrides:
- files: "*.md"
options:
parser: remark
proseWrap: always
printWidth: 80
328 changes: 226 additions & 102 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,148 +1,272 @@
# Contributing

Contributions are welcome, and they are greatly appreciated! Every
little bit helps, and credit will always be given.
Your contributions are valued and play a significant role in the continuous
improvement of **Sugar**. We welcome contributions of all forms and acknowledge
all efforts.

You can contribute in many ways:
## How You Can Contribute

## Types of Contributions
Contributions can be made in various ways, outlined below:

### Report Bugs

Report bugs at https://github.com/osl-incubator/sugar.git/issues.
If you encounter a bug in **Sugar**, please report it via our GitHub issues page
at:
[https://github.com/osl-incubator/sugar/issues](https://github.com/osl-incubator/sugar/issues).

If you are reporting a bug, please include:
When reporting a bug, kindly include the following information to aid in the
issue's resolution:

- Your operating system name and version.
- Any details about your local setup that might be helpful in
troubleshooting.
- Detailed steps to reproduce the bug.
- The name and version of your operating system.
- Any relevant details about your setup that might assist in diagnosing the
issue.
- A step-by-step guide to reproduce the bug.

### Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” and
“help wanted” is open to whoever wants to implement it.
You can contribute by fixing bugs identified in the GitHub issues. Issues tagged
with both "bug" and "help wanted" are available for anyone to work on.

### Implement Features

Look through the GitHub issues for features. Anything tagged with
“enhancement” and “help wanted” is open to whoever wants to implement
it.
Feature development is another way to contribute. Review the GitHub issues for
requested features. Issues labeled with "enhancement" and "help wanted" are open
for implementation.

### Write Documentation

sugar could always use more documentation,
whether as part of the official sugar docs,
in docstrings, or even on the web in blog posts, articles, and such.
There's always a need for more documentation for **Sugar**. This could be
through enhancing the official documentation, contributing to docstrings, or
sharing knowledge via blog posts, articles, and other media.

### Submit Feedback

The best way to send feedback is to file an issue at
https://github.com/osl-incubator/sugar.git/issues.

If you are proposing a feature:

- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to
implement.
- Remember that this is a volunteer-driven project, and that
contributions are welcome :)

## Get Started!

Ready to contribute? Here’s how to set up `sugar` for local development.

1. Fork the `sugar` repo on GitHub.

2. Clone your fork locally::

$ git clone [email protected]:your_name_here/sugar.git

3. Install your local copy into a virtualenv. Assuming you have
virtualenvwrapper installed, this is how you set up your fork for
local development::

$ mkvirtualenv sugar
$ cd sugar/
$ python setup.py develop
Feedback is crucial for project improvement. To submit feedback or propose a
feature:

- File an issue at
[https://github.com/osl-incubator/sugar/issues](https://github.com/osl-incubator/sugar/issues).
- For feature proposals, please provide a detailed explanation of how the
feature would function, aim for a narrow scope to facilitate easier
implementation, and remember, **Sugar** is a volunteer-driven project, and
we welcome contributions.

## Requirements

Before you begin contributing to the Sugar project, there are several technical
prerequisites and best practices you should be familiar with. This section
outlines the key requirements to ensure a smooth and productive contribution
process.

### Conda Environment

Conda is a versatile tool that provides package, dependency, and environment
management for various programming languages. In the Sugar project, we leverage
Conda to manage virtual environments and package dependencies effectively.

- **Environment Setup**: We strongly advise using a Conda environment while
working with Sugar. If Conda is not installed on your system, you can
download it from [Miniforge](https://github.com/conda-forge/miniforge). For
an introductory overview of Conda, consider watching this
[Conda Basics video](https://learning.anaconda.cloud/conda-basics).
- **Best Practices**: Avoid installing packages in the base Conda environment.
Always create and activate a new environment for each project to prevent
dependency conflicts and ensure a clean workspace.

### Git

Our collaborative efforts are facilitated through Git and GitHub. Understanding
the fundamentals of Git is crucial for effective participation.

- **Learning Resources**: If you're new to Git, we recommend starting with the
[Software Carpentry Git Lesson](https://swcarpentry.github.io/git-novice/),
which covers essential Git concepts and workflows.
- **Quick Reference**: For a concise summary of common Git commands, refer to
this
[Git Cheat Sheet](https://education.github.com/git-cheat-sheet-education.pdf)
provided by GitHub.
- **Configuration Tips**:
- To streamline your workflow, configure Git to use `rebase` by default
for pulling changes with `git config --global pull.rebase true`.
- Familiarize yourself with the `git rebase` command for updating branches
from a remote repository. Although more complex, it is preferred over
the default merge commit strategy. For an in-depth explanation, visit
[Atlassian's guide on merging vs. rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing).
- **Workflow**: The standard open-source development workflow includes forking
a repository, cloning the fork locally, and configuring an `upstream` remote
for the original repository. Detailed instructions can be found in
[GitHub's guide to configuring a remote for a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork).

### Python

Familiarity with Python and adherence to best practices is important for
contributing to Sugar.

- **Style Guide**: Follow the PEP 8 style guide for Python code, available at
[PEP8](https://peps.python.org/pep-0008/).
- **Best Practices**: pyOpenSci offers a comprehensive guide for writing
Python packages, which can be found
[here](https://www.pyopensci.org/python-package-guide/index.html).
- **Advanced Learning**: To deepen your understanding of Python and general
programming concepts, consider enrolling in the
[Design of Computer Programs](https://www.udacity.com/course/design-of-computer-programs--cs212)
course on Udacity. Though challenging and based on Python 2, it provides
valuable insights into advanced Python usage and computer programming
principles.

### Docker

Docker and Docker Compose are fundamental components within the **sugar**
project infrastructure. These technologies facilitate the creation, deployment,
and management of isolated environments, making them integral to development and
testing processes in **sugar**.

To gain a foundational understanding of Docker and Docker Compose, consider
exploring the following tutorial, which provides a comprehensive introduction to
both technologies:
[Educative: Docker Compose Tutorial](https://www.educative.io/blog/docker-compose-tutorial).
This resource is designed to help newcomers grasp the essentials of Docker and
Docker Compose, covering everything from basic concepts to advanced usage
scenarios.

A thorough comprehension of Docker and Docker Compose is crucial for
contributing to the **sugar** project, as all development and deployment
workflows are designed around these technologies.

### How to Get Support

Should you require assistance, please join our community on the Open Science
Labs Discord server at
[https://opensciencelabs.org/discord](https://opensciencelabs.org/discord).
Here, you can participate in the incubator program and ask questions about Sugar
in its dedicated channel. You are also welcome to explore and join other groups
that align with your interests.

## Setting Up for Local Development

To contribute to `sugar`, follow these steps to set up your development
environment:

1. **Fork the Repository**: Begin by forking the `sugar` repository on GitHub to
your own account.

2. **Clone Your Fork Locally**: Clone the forked repository to your local
machine and navigate into the project directory.

```bash
$ git clone [email protected]:your_username/sugar.git
$ cd sugar
```

3. **Install Dependencies**: Use `mamba` to create a Conda environment and
`poetry` for managing Python dependencies.

```bash
$ mamba env create --file conda/dev.yaml --force
$ poetry config virtualenvs.create false
$ poetry install
```

4. **Create a Development Branch**: Make a dedicated branch for your bugfix or
feature.

```bash
$ git checkout -b name-of-your-bugfix-or-feature
```

4. Create a branch for local development::
5. **Make Changes Locally**: You are now ready to implement your changes or
improvements.

$ git checkout -b name-of-your-bugfix-or-feature
6. **Install and Use Pre-commit Hooks**: `sugar` utilizes `pre-commit` hooks to
ensure code quality. Install them locally and they will automatically run on
each commit.

Now you can make your changes locally.
```bash
$ pre-commit install
$ pre-commit run --all-files
```

5. When you’re done making changes, check that your changes pass flake8
and the tests, including testing other Python versions with tox::
To bypass the hooks temporarily, use `git commit` with `--no-verify`.

$ makim tests.linter
$ makim tests.unit
7. **Run Smoke Tests**: Quickly validate the functionality of your changes with
smoke tests.

To get flake8 and tox, just pip install them into your virtualenv.
```bash
$ makim tests.smoke
```

6. Commit your changes and push your branch to GitHub::
Always complement smoke tests with thorough unit testing to ensure code
integrity.

$ git add . $ git commit -m “Your detailed description of your
changes.” $ git push origin name-of-your-bugfix-or-feature
8. **Unit Testing with `pytest`**: `sugar` leverages `pytest` for unit testing,
along with `pytest-cov` for coverage analysis. Run unit tests using:

7. Submit a pull request through the GitHub website.
```bash
$ python -m pytest
```

## Pull Request Guidelines
or

Before you submit a pull request, check that it meets these guidelines:
```bash
$ makim tests.unittest
```

1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated.
Put your new functionality into a function with a docstring, and add
the feature to the list in README.rst.
3. The pull request should work for Python >= 3.8.
9. **Commit and Push Changes**: Stage, commit, and push your changes to GitHub.
After setting the upstream branch once, subsequent pushes only require
`git push`.

## Tips
```bash
$ git add .
$ git commit -m "Detailed description of your changes."
$ git push --set-upstream origin <branch name>
```

To run a subset of tests::
10. **Submit a Pull Request**: Once your changes are pushed, go to the GitHub
website to submit a pull request for review.

```
$ pytest tests.test_containers_sugar
```
## Release Process

## Release
The **Sugar** project utilizes `semantic-release` to automate the release
process, basing new releases on the content of commit messages.

This project uses semantic-release in order to cut a new release
based on the commit-message.
### Commit Message Format

### Commit message format
`semantic-release` analyzes commit messages to assess the impact of changes made
to the codebase. Adhering to a standardized commit message format allows
`semantic-release` to automatically determine the next semantic version number,
generate a comprehensive changelog, and publish the release.

**semantic-release** uses the commit messages to determine the consumer
impact of changes in the codebase. Following formalized conventions for
commit messages, **semantic-release** automatically determines the next
[semantic version](https://semver.org) number, generates a changelog and
publishes the release.
While `semantic-release` defaults to the
[Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format),
**Sugar** adopts the "Conventional Commits" standard
([https://www.conventionalcommits.org/en/v1.0.0/](https://www.conventionalcommits.org/en/v1.0.0/)).
This standard facilitates more detailed commit messages, especially for
"breaking changes".

By default, **semantic-release** uses [Angular Commit Message
Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format).
The commit message format can be changed with the `preset` or `config`
options_ of the
[@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options)
and
[@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options)
plugins.
Given the project's use of the `squash and merge` strategy for merging pull
requests, it is crucial to format the PR title according to the commit message
standards.
Tools such as [commitizen](https://github.com/commitizen/cz-cli) or
[commitlint](https://github.com/conventional-changelog/commitlint) can
be used to help contributors and enforce valid commit messages.
To aid contributors in crafting compliant commit messages, tools like
[commitizen](https://github.com/commitizen/cz-cli) and
[commitlint](https://github.com/conventional-changelog/commitlint) are
recommended. These tools help ensure that commit messages adhere to the required
format.
The table below shows which commit message gets you which release type
when `semantic-release` runs (using the default configuration):
The following table illustrates how different commit messages correspond to the
type of release generated by `semantic-release`, according to its default
configuration:
| Commit message | Release type |
|----------------------------------------------------------------|------------------|
| `fix(pencil): stop graphite breaking when pressure is applied` | Fix Release |
| `feat(pencil): add 'graphiteWidth' option` | Feature Release |
| `perf(pencil): remove graphiteWidth option` | Chore |
| `BREAKING CHANGE: The graphiteWidth option has been removed` | Breaking Release |
| Commit Message Example | Release Type |
| ------------------------------------------------------------ | ------------- |
| `fix(pencil): stop graphite breaking when too much pressure` | Patch Release |
| `feat(pencil): add 'graphiteWidth' option` | Minor Release |
| `perf(pencil): optimize 'graphiteWidth' calculation` | Patch Release |
| `fix(pencil)!: 'graphiteWidth' option removed` | Major Release |
source:
<https://github.com/semantic-release/semantic-release/blob/master/README.md#commit-message-format>
**Note**: Within the Conventional Commits standard, appending `!` to the message
prefix indicates a breaking change.
As this project uses the `squash and merge` strategy, ensure to apply
the commit message format to the PR's title.
For more details on the commit message format used by `semantic-release`, visit
the
[semantic-release documentation](https://github.com/semantic-release/semantic-release#commit-message-format).

0 comments on commit 2693e70

Please sign in to comment.