<commit_before>Contributing to the Globus CLI
==============================

First off, thank you so much for taking the time to contribute! :+1:

This document is a set of guidelines for making modifications to the CLI, not a
set of strict rules.
Sometimes it's okay to go off-book if you have a good reason, so use your best
judgement.
Feel free to propose changes to this document in a pull request.

QuickStart
----------

Impatient? Want to get hacking on this right away? Have ideas and can't wait to
share them with us?
A few quick rules if you don't want to read this full document:

  - All of your code *must* pass `flake8`. We won't consider merging code which
      doesn't pass `flake8`
  - Check if there's a matching
      https://github.com/globus/globus-sdk-python/issues[issue]
      before opening a new issue or pull request

Developer Setup
---------------

These steps should help you setup a development environment for the Globus CLI.

  1. Clone repo:
     `git clone <EMAIL>:globus/globus-cli.git && cd globus-cli`
  2. Create a virtualenv for development. We recommend the name `.venv`:
     `virtualenv .venv`. Activate it with `source .venv/bin/activate`
  3. Setup the CLI in develop mode: `python setup.py develop`

You should now have, in the confines of your virtualenv, the `globus-cli`
installed, pointed at your local copy of the repo. `globus` will invoke code
directly out of the repo (that's what `python setup.py develop` does).
You can write and test commands interactively in this setup.

Reporting Bugs
--------------

We welcome any and all bugs on the
https://github.com/globus/globus-cli/issues[GitHub Issue Tracker].

However, the best bug reports are ones which follow the following rules and
answer the following questions:

  - *What version of python are you running?* The CLI supports a wide variety
      of python versions, and a wide class of bugs are results of version
      incompatibilities between those versions. Give us the result of
      `python --version`
  - *What other python packages do you have installed?* The best thing in this
      case is to show us the results of `pip freeze`
  - *Check for duplicates*. You don't have to scour our issue tracker, but do a
      quick search to try to make sure you aren't reporting a known bug.
  - *Use a clear descriptive title* for the issue you are reporting. The best
      titles are short, but also uniquely describe the problem.
  - *Provide a specific example of how to reproduce*. Give an example command,
      and describe, to the best of your ability, the states of the
      resources with which you are working.


Requesting Features & Improvements
----------------------------------

When requesting new features, there are a few things we ask you to do in order
to help us prioritize.

  - *Tell us why you want it*. If you request a feature, but we don't know what
      you want it for, it's hard for us to know how critical the request is.
      Tell us as much of the *why* as you can, not just the *what*.
  - *How important is this feature to you?* Clearly describe to us how
      important this feature is for your use case. Obviously, this is not the
      only thing we weigh when prioritizing features, but it is important for
      us to know.
  - *Do you have an idea of what a command should look like?* If you have some
      thoughts about what you would like a command to look like, please include
      an example of what you'd like to see.

Submitting Pull Requests
------------------------

The most important thing about a pull request is that it meets the standards
defined in this document's <<style-guide,Style Guide>>.

Beyond that, we have a few recommendations:

  - *Make sure it merges cleanly*. We will request that you rebase if your PR
      has merge conflicts.
  - *List any issues closed by the pull request*.
  - *Squash intermediate commits*. Help us keep our git history clean by doing
      a `git rebase --interactive` and squashing typo fixes, aborted
      implementations, and other cruft. We may request that you squash your
      history if there are many fixup commits.

Additionally, make sure you follow our rules for
<<commit-messages,Commit Messages>>

Commit Messages
---------------

A few basic ground rules for what ideal commits should look like.

  - No lines over 72 characters
  - No GitHub emoji -- use your words
  - Reference issues and pull requests where appropriate
  - Present tense and imperative mood

Style Guide
-----------

Some rules and tips for the python and documentation in this project.

  - All code must pass `flake8`. That means PEP8 compliant and passing pyflakes
  - All options should have descriptive help text
  - For complex functionality, include sample usage in the helptext for the
      relevant command. If it's a specific flag or feature that has complex
      behavior, make it a separate section of the help text. See
      `globus transfer async-transfer --help` for an example
  - Comment liberally in source
  - Every command gets its own module, named after the command name
  - Use absolute imports everywhere
  - Avoid circular imports whenever possible -- given the choice between adding
      a new module or adding a circular import, add the new module
  - Import non-`globus_cli` modules and packages before importing from within
      `globus_cli`
  - Think very hard before adding a new dependency -- keep the dependencies of
      `globus_cli` as lightweight as possible
  - Use named parameters, not positional arguments
  - Use the verbs `create`, `show`, `update`, and `remove` for underlying API
      CRUD operations<commit_msg>Add section to contrib doc about releasing<commit_after>Contributing to the Globus CLI
==============================

First off, thank you so much for taking the time to contribute! :+1:

This document is a set of guidelines for making modifications to the CLI, not a
set of strict rules.
Sometimes it's okay to go off-book if you have a good reason, so use your best
judgement.
Feel free to propose changes to this document in a pull request.

QuickStart
----------

Impatient? Want to get hacking on this right away? Have ideas and can't wait to
share them with us?
A few quick rules if you don't want to read this full document:

  - All of your code *must* pass `flake8`. We won't consider merging code which
      doesn't pass `flake8`
  - Check if there's a matching
      https://github.com/globus/globus-sdk-python/issues[issue]
      before opening a new issue or pull request

Developer Setup
---------------

These steps should help you setup a development environment for the Globus CLI.

  1. Clone repo:
     `git clone <EMAIL>:globus/globus-cli.git && cd globus-cli`
  2. Create a virtualenv for development. We recommend the name `.venv`:
     `virtualenv .venv`. Activate it with `source .venv/bin/activate`
  3. Setup the CLI in develop mode: `python setup.py develop`

You should now have, in the confines of your virtualenv, the `globus-cli`
installed, pointed at your local copy of the repo. `globus` will invoke code
directly out of the repo (that's what `python setup.py develop` does).
You can write and test commands interactively in this setup.

Reporting Bugs
--------------

We welcome any and all bugs on the
https://github.com/globus/globus-cli/issues[GitHub Issue Tracker].

However, the best bug reports are ones which follow the following rules and
answer the following questions:

  - *What version of python are you running?* The CLI supports a wide variety
      of python versions, and a wide class of bugs are results of version
      incompatibilities between those versions. Give us the result of
      `python --version`
  - *What other python packages do you have installed?* The best thing in this
      case is to show us the results of `pip freeze`
  - *Check for duplicates*. You don't have to scour our issue tracker, but do a
      quick search to try to make sure you aren't reporting a known bug.
  - *Use a clear descriptive title* for the issue you are reporting. The best
      titles are short, but also uniquely describe the problem.
  - *Provide a specific example of how to reproduce*. Give an example command,
      and describe, to the best of your ability, the states of the
      resources with which you are working.


Requesting Features & Improvements
----------------------------------

When requesting new features, there are a few things we ask you to do in order
to help us prioritize.

  - *Tell us why you want it*. If you request a feature, but we don't know what
      you want it for, it's hard for us to know how critical the request is.
      Tell us as much of the *why* as you can, not just the *what*.
  - *How important is this feature to you?* Clearly describe to us how
      important this feature is for your use case. Obviously, this is not the
      only thing we weigh when prioritizing features, but it is important for
      us to know.
  - *Do you have an idea of what a command should look like?* If you have some
      thoughts about what you would like a command to look like, please include
      an example of what you'd like to see.

Submitting Pull Requests
------------------------

The most important thing about a pull request is that it meets the standards
defined in this document's <<style-guide,Style Guide>>.

Beyond that, we have a few recommendations:

  - *Make sure it merges cleanly*. We will request that you rebase if your PR
      has merge conflicts.
  - *List any issues closed by the pull request*.
  - *Squash intermediate commits*. Help us keep our git history clean by doing
      a `git rebase --interactive` and squashing typo fixes, aborted
      implementations, and other cruft. We may request that you squash your
      history if there are many fixup commits.

Additionally, make sure you follow our rules for
<<commit-messages,Commit Messages>>

Commit Messages
---------------

A few basic ground rules for what ideal commits should look like.

  - No lines over 72 characters
  - No GitHub emoji -- use your words
  - Reference issues and pull requests where appropriate
  - Present tense and imperative mood

Style Guide
-----------

Some rules and tips for the python and documentation in this project.

  - All code must pass `flake8`. That means PEP8 compliant and passing pyflakes
  - All options should have descriptive help text
  - For complex functionality, include sample usage in the helptext for the
      relevant command. If it's a specific flag or feature that has complex
      behavior, make it a separate section of the help text. See
      `globus transfer async-transfer --help` for an example
  - Comment liberally in source
  - Every command gets its own module, named after the command name
  - Use absolute imports everywhere
  - Avoid circular imports whenever possible -- given the choice between adding
      a new module or adding a circular import, add the new module
  - Import non-`globus_cli` modules and packages before importing from within
      `globus_cli`
  - Think very hard before adding a new dependency -- keep the dependencies of
      `globus_cli` as lightweight as possible
  - Use named parameters, not positional arguments
  - Use the verbs `create`, `show`, `update`, and `remove` for underlying API
      CRUD operations


Releasing a Version
-------------------

If you are a CLI maintainer, you need to be able to do a release.

Setup:

  - Make sure you have a pypi account
  - Setup your credentials for twine (the pypi upload tool) https://github.com/pypa/twine[twine docs for detail]
  - Make sure you have a gpg key setup for use with git

Do it:

  - `rm -r dist/` to make sure there are no old or weird source dists lying around
  - `make upload` to build new source dists in `dist/` and upload via twine
  - `git tag -s $VERSION` and write `v${VERSION}` in the tag. e.g. `v1.7.0`
  - Ensure that `docs.globus.org` gets updated with new docs/changelog
      Procedure is set in that repo.
{'fraction_non_alphanumeric': 0.07680172700099634, 'fraction_numerical': 0.0019096645632680172, 'mean_word_length': 3.0460194827007054, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 5, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5151199', 'n_tokens_mistral': 3166, 'n_tokens_neox': 3032, 'n_words': 1797}