Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (78 loc) · 3.45 KB

CONTRIBUTING.md

File metadata and controls

105 lines (78 loc) · 3.45 KB

Contributing

Developing cnlp-transformers

The first things to do when contributing to the code base here are to clone this repository and set up your Python environment.

  1. Clone this repository:
# Either the HTTPS method...
$ git clone https://github.com/Machine-Learning-for-Medical-Language/cnlp_transformers.git
# ...or the SSH method
$ git clone git@github.com:Machine-Learning-for-Medical-Language/cnlp_transformers.git
  1. Enter the repo: cd cnlp_transformers
  2. You will need Python 3.8. Either a venv virtual environment or a Conda environment should work. Create your environment and activate it.
  3. Install the development dependencies: pip install -r dev-requirements.txt
  4. Install cnlp-transformers in editable mode: pip install -e .

The remainder of the instructions on this document will assume that you have installed the development dependencies.

Proposing changes

If you have changes to the code that you wish to contribute to the repository, please follow these steps.

  1. Fork the project on GitHub.
  2. Add your fork as a remote to push your work to. Replace {username} with your username. This names the remote "fork", the default Machine-Learning-for-Medical-Language remote is "origin".
# Either the HTTPS method...
$ git remote add fork https://github.com/{username}/cnlp_transformers.git
# ...or the SSH method
$ git remote add fork git@github.com:{username}/cnlp_transformers.git
  1. Make a new branch and set your fork as the upstream remote:
$ git switch -c your-branch-name  # or git checkout -b
$ git push --set-upstream fork your-branch-name
  1. Open an issue that motivates the change you are making if there is not one already.
  2. Make your changes in your-branch-name on your fork.
  3. Open a PR to close the issue.

For Maintainers: Building and uploading new package version

Building

First, increment the version number in src/cnlpt/VERSION if it isn't already.

Then, run build:

$ python -m build

This will build the package in the ./dist/ directory, creating it if it does not exist.

Uploading

In preparation, set up your PyPI API key if you haven't already:

  1. Log into your PyPI account
  2. Generate an API key for the cnlp-transformers project here
  3. Create a file ~/.pypirc:
[pypi]
username = __token__
password = <the token value, including the `pypi-` prefix>

Only follow these steps after merging the new version branch into master.

  1. Checkout the merge commit for the new version; this will usually be the latest commit in master.

  2. Before continuing, ensure the version number in src/cnlpt/VERSION has been incremented from the previous version on PyPI.

  3. Delete the contents of the ./dist/ directory if it exists.

  4. Build the new version according to the building instructions above.

  5. Upload to PyPI with twine:

    $ python -m twine upload dist/*

Building the documentation

To rebuild the autodoc toctrees and the transformers Intersphinx mappings, run build_doc_source.sh.

To build the docs locally for testing documentation changes before uploading to readthedocs, first uncomment lines 36 and 65 on docs/conf.py, then execute the following:

$ cd docs
$ make html

This will write the docs to docs/build/html; simply open docs/build/html/index.html in your browser of choice to view the built documentation.