Skip to content

Latest commit

 

History

History
227 lines (159 loc) · 6.61 KB

CONTRIBUTING.md

File metadata and controls

227 lines (159 loc) · 6.61 KB
Raw

Contributing to Small-Text

Happy to see you here. Contributions are always welcome. We need help, among others, in the form of code or documentation.

❤️ Even if you tend to doubt yourself, we encourage you to try and pick a small part of small-text that can be improved. Every little bit of effort is appeciated and we welcome everyone who is willing to learn.

Click here to see the list of contributors.

Table of Contents

  1. How to Contribute
  2. Support us
  3. Development
  4. Documentation
  5. Workflows

License / Preliminaries

Important: By contributing you agree to the following:

  1. License: This project is licensed under the MIT License (see LICENSE). By contributing you agree to license your contributions under this license as well.
  2. All contributions are subject to the Developer Certificate of Origin.

You are responsible to guarantee that the code is a) either written by yourself or, or b) that it is both usable under the MIT License and properly attributed. Please mark any code fragments that you did not write yourself in the code and mention them in the pull request so that a second person can review this.

How to Contribute

For contributions, there are both code and non-code contributions. Both are equally welcome. As a small token of appreciation, with your first contribution you can put yourself on the list of contributors (if the commit contributes to code or documentation).

Types of Contribution

  • Report Bugs
  • Suggest Enhancements
  • Documentation
  • Code

Support us

Apart from contributions, if you like our project you can also support us by:

  • Consider giving us a github star
  • Use small-text in your applications or experiments.
  • Write a blog post small-text or your specific use case
  • Share small-text on Twitter or LinkedIn.

How to work on an issue (bug, feature, documentation, other)

  1. Search for an existing issue related to your problem. If none exists yet then create an issue stating the problem and that you are working on it.
  2. Fork the repository. Create a new branch that branches off the dev branch.
  3. Apply your changes.
  4. Make sure the unit / integration tests succeed.
  5. Create a pull request. (You can also create the pull requets earlier if you mark it as "work in progress").

Pull Request Checklist

  1. Check that the documentation can be built:

    cd docs && make html

  2. Check that the documentation examples run:

    cd docs && make doctest

Development

Code Conventions

  1. Code style should adhere to the .flake8 config (except in justified cases).
flake8

Building the Documentation

The documentation can be generated using sphinx:

pip install sphinx sphinx-rtd-theme
cd docs/
make
sphinx-build . _build/ -b linkcheck
sphinx-build . _build/ -b doctest

Testing

If you do this for the first time you have to install the development dependencies:

pip install -r requirements-dev.txt

Running the unit tests

pytest -m 'not optional' --cov small_text --cov-append tests/unit/

Without pytorch tests:

pytest -m 'not pytorch and not optional' --cov small_text --cov-append tests/unit/

Running the integration tests:

pytest -m 'not optional' --cov small_text --cov-append tests/integration

Without pytorch tests:

pytest -m 'not pytorch and not optional' --cov small_text --cov-append tests/integration

Continuous Integration

We use a CI Pipeline which is unfortunately not public yet, but this might change in the future.

This pipeline checks the following:

  • Checks if small-text can be installed with and without extra requirements.
  • Checks if the unit/integration tests complete successfully.
  • Checks if the examples can be executed successfully.
  • Checks whether the documentation can be built.

Documentation

This section refers to the (sphinx) online documentation. This may include adapting certain parts of the docstrings but the focus here is the final result. See the subsection under Development on how to build the documentation.

Documentation Conventions

The same thing should unambiguously be referred to in the same way (i.e. don't use different names or spellings for one single concept) and similar things should be treated in the same way.

General

We use numpydoc docstrings.

Spellings

  • "small-text" is preferred over "Small-Text" in cases where the first letter is capitalized the latter should be used
  • multi-label instead of multi label (analogous: multi-class)
  • dataset instead of data set (but: train set, test set)

Workflows

Release Checklist

The following steps need to be done before a new release can be created.

Raising the Version

  • Update small_text/version.json
  • examples/notebooks: Set the small-text version to the new release.
    • Check notebook using a temporary small-text installation via github.
  • docs/index.rst: Set the small-text version to the new release.
  • README.md (Links "Notebooks" / "Code Examples")
    • Documentation Badge should link to the version of the most recent release (link AND img)
    • Link references at the bottom should point to the most recent release
    • Notebook links should point to the most recent release
  • Set the version and date in CHANGELOG.md
    • Make sure the changelog is complete
  • Update the "News" section in README.md

Checking for Correctness

  • Check every step of the above Pull Request Checklist
  • Check if the CI Pipeline runs successfully
  • Documentation
    • Check if conda versions in docs/install.rst match those in setup.py
    • Run the sphinx doctests 
      • sphinx-build SOURCEDIR OUTPUTDIR -b doctest
    • Run sphinx linkcheck: 
      • sphinx-build SOURCEDIR OUTPUTDIR -b linkcheck
      • Links containing the new version tag (e.g., v1.0.0) will fail.

Create a Release

  • Create a git tag: v<VERSION> (e.g., v1.0.0)

  • Push tags and code to github

  • Create new version at Read the Docs

    • Run sphinx linkcheck (yes, again):
    • sphinx-build SOURCEDIR OUTPUTDIR -b linkcheck

  • Create a release on testpypi

    • If successful:
      • Create a new Zenodo version and update DOI in README.md
      • Delete and create the tag again at the current head commit
      • Create a release on pypi

  • Create a release on github

  • Create a new condaforge release