Skip to content

Latest commit

 

History

History
262 lines (167 loc) · 7.91 KB

CONTRIBUTING_EN.md

File metadata and controls

262 lines (167 loc) · 7.91 KB

Contributing

Thanks for taking the time to contribute! 🙇‍♀️🙇‍♂️ Every little bit of help counts!

First Contribution

How to make your first contribution:

1. Create a GitHub Account

Make sure you have a GitHub account and you are logged in with it.

2. Find an Issue to Work With

Visit the brutils issues page and find an issue you would like to work with and no one assigned to it yet.

Send a comment in the issue asking to work with it. Something like: "hey, can I work on this?".

Wait until someone assign you to the ticket. Once you are assigned to it, you can move to the next step.

Please, feel free to ask any questions in the issue's page before or during the development process.

When starting to contribute to the project, it is advisable to pick one issue at a time. This helps ensure that others also have the opportunity to collaborate and prevents resources from staying inactive for too long.

3. Install Git

Make sure you have Git installed.

4. Fork the Project

Fork the brutils repository.

5. Clone your Fork

Clone your fork locally.

6. Create a New Branch

Go into the brutils folder:

$ cd brutils-python

And create a new branch:

$ git checkout -b <issue_number>

7. Run brutils locally

Installation

Requirements

Create a virtualenv for brutils and activate it:

$ make shell

Note: You need to run make shell every time you open a new terminal window/tab.

Install the dependencies:

$ make install

Using locally

$ make run-python

Now, you can use it in the same way described in the README.md file.

Tests

$ make test

8. Make your changes

Now is the step where you can implement your changes in the code.

It is important to notice that we document our code using docstrings. Modules, classes, functions, and methods should be documented. Your changes should also be well documented and should reflect updated docstrings if any of the params were changed for a class/attributes or even functions.

We follow the given pattern below to keep consistency in the docstrings:

class Example:
    """Explain the purpose of the class

    Attributes:
        x[dict]: Short explanation here
        y[type, optional]: Short explanation here

    """

    def __init__(self, x, y=None):
        self.x = x
        self.y = y

    def foobar(self, w):
        """Purpose if the function

        Args:
            w[str]: Short explanation here

        Returns:
            value[str]: Short explanation here

        """
        ...
        return value

One last thing to keep in mind while self-documenting code with docstrings that you can ignore docstrings in property decorators and magic methods.

9. Test your changes

Write new tests

Make sure you have created the necessary tests for every new change you made.

Make sure all tests passed

Run all the tests with make test and make sure that they all passed.

PRs will not be merged if there is any test missing or failing.

10. Commit and push your changes

Commit the changes:

$ git commit -a -m "<commit_message>"

Push your commit to GitHub:

$ git push --set-upstream origin <issue_number>

Create the number of changes/commits you need and push them.

11. Add changelog entries

Add a changelog entry to CHANGELOG.md.

12. Create a GitHub PR

Create a GitHub PR.

13. Update your branch if needed.

Make sure your branch is updated with main.

Release a New Version

Here you will find how to deploy a new production version of brutils:

1. Create a Release Issue

Create the Issue

For the issue creation, you can use the feature template, with the issue name being Release v<version>. Example

Create a Branch

The branch name created for the release is related to the Issue number, as shown in this example

2. Create a Release PR

Bump the lib Version

Increment the version number, following the Semantic Versioning, in the pyproject.toml file: https://github.com/brazilian-utils/brutils-python/blob/main/pyproject.toml#L3

Update the CHANGELOG.md

Add a new version title with the new version number and the current date, like this.

And add the version links, like this

Create the PR

Create a PR named Release v<version> containing these two changes above.

Example of Release PR

Merge the PR

Once the PR has been accepted and passed on all checks, merge it.

2. Deploy via GitHub

Deploy production is automatically done when a new release is created on GitHub.

  • The tag version should be v<version> (e.g v2.0.0).
  • The release title should be the same as tag version (e.g v2.0.0).
  • The release description should be the content copied from the CHANGELOG.md file from the corresponding version section.

Real examples are available at: https://github.com/brazilian-utils/brutils-python/releases

When the Deploy on GitHub is done, the new version will be also automatically deployed on PyPI. Download the new brutils version from PyPI and test if everything is working as expected.