Skip to content

Commit

Permalink
docs: Update the contributing guide (#96)
Browse files Browse the repository at this point in the history
  • Loading branch information
@xmnlab
xmnlab authored Feb 29, 2024
1 parent 08761b3 commit 303b29c
Show file tree
Hide file tree
Showing 3 changed files with 227 additions and 135 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
354 changes: 219 additions & 135 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,169 +1,253 @@
# 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 **Makim**. 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/makim.git/issues.
If you encounter a bug in **Makim**, please report it via our GitHub issues page
at:
[https://github.com/osl-incubator/makim/issues](https://github.com/osl-incubator/makim/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

makim could always use more documentation, whether as part of the official makim
docs, in docstrings, or even on the web in blog posts, articles, and such.
There's always a need for more documentation for **Makim**. 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/makim.git/issues.
Feedback is crucial for project improvement. To submit feedback or propose a
feature:

- File an issue at
[https://github.com/osl-incubator/makim/issues](https://github.com/osl-incubator/makim/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, **Makim** is a volunteer-driven project, and we
welcome contributions.

## Requirements

Before you begin contributing to the Makim 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 Makim project, we leverage
Conda to manage virtual environments and package dependencies effectively.

- **Environment Setup**: We strongly advise using a Conda environment while
working with Makim. 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 Makim.

- **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.

### 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 Makim
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 `makim`, follow these steps to set up your development
environment:

1. **Fork the Repository**: Begin by forking the `makim` 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/makim.git
$ cd makim
```

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
```

5. **Make Changes Locally**: You are now ready to implement your changes or
improvements.

6. **Install and Use Pre-commit Hooks**: `makim` utilizes `pre-commit` hooks to
ensure code quality. Install them locally and they will automatically run on
each commit.

```bash
$ pre-commit install
$ pre-commit run --all-files
```

To bypass the hooks temporarily, use `git commit` with `--no-verify`.

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

```bash
$ makim tests.smoke
```

Always complement smoke tests with thorough unit testing to ensure code
integrity.

8. **Unit Testing with `pytest`**: `makim` leverages `pytest` for unit testing,
along with `pytest-cov` for coverage analysis. Run unit tests using:

```bash
$ python -m pytest
```

or

```bash
$ makim tests.unittest
```

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`.

If you are proposing a feature:
```bash
$ git add .
$ git commit -m "Detailed description of your changes."
$ git push --set-upstream origin <branch name>
```

- 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 :)
10. **Submit a Pull Request**: Once your changes are pushed, go to the GitHub
website to submit a pull request for review.

## Get Started!
## Release Process

For development, we encourage you to use `conda`. If you don't know what is
that, check these links:
The **Makim** project utilizes `semantic-release` to automate the release
process, basing new releases on the content of commit messages.

- In Spanish:
https://opensciencelabs.org/blog/como-instalar-y-comenzar-utilizar-conda/
- In English: https://cloudsmith.com/blog/what-is-conda/
### Commit Message Format

We recommend you to use mamba-forge, a combination of miniconda + conda-forge +
mamba. You can download it from here:
https://github.com/conda-forge/miniforge#mambaforge
`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.

Ready to contribute? Here’s how to set up `makim` for local development.
While `semantic-release` defaults to the
[Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format),
**Makim** 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".

1. Fork the `makim` repo on GitHub.
2. Clone your fork locally:
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.

```bash
$ git clone [email protected]:your_name_here/makim.git
```
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.

3. Create a conda environment and activate it:
The following table illustrates how different commit messages correspond to the
type of release generated by `semantic-release`, according to its default
configuration:

```bash
$ mamba env create --file conda/dev.yaml
```
| 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 |

and
**Note**: Within the Conventional Commits standard, appending `!` to the message
prefix indicates a breaking change.

```bash
$ conda activate makim
```

4. Install your local project copy into your conda environment:

```bash
$ poetry install
```

5. Create a branch for local development::

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

6. When you’re done makimg changes, check that your changes pass flake8 and the
tests, including testing other Python versions with tox::

```bash
$ makim tests.linter
$ makim tests.unittest
$ makim tests.smoke
```

7. Commit your changes and push your branch to GitHub::

```bash
$ git add . $ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature
```

8. Submit a pull request through the GitHub website.

## Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

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.

## Tips

To run a subset of tests::

```
$ pytest tests.test_containers_sugar
```

## Release

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

### Commit message format

**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.

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.

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.

The table below shows which commit message gets you which release type when
`semantic-release` runs (using the 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 |
| `feat(pencil)!: The graphiteWidth option has been removed` | Breaking Release |

source:
<https://github.com/semantic-release/semantic-release/blob/master/README.md#commit-message-format>

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 303b29c

Please sign in to comment.