Development ¶

Basic Setup ¶

pip install -r dev-requirements.txt
pip install -e .

General Process ¶

Create an issue
Discuss approach
Complete contribution in a fork or branch.
Submit a pull-request
Respond to reviews

Periodically the develop branch will be merged with master and a tagged release will be made and distributed to PyPI.

By making any contribution to the projects, contributors self-certify to the Contributor Agreement.

Issues ¶

Search existing issues to see if your issue has already been brought up.
Create new issues to start discussion on a new topic, feature requests, and bugs; linking to any other relevant issues.
Fill out issue template to the best of your ability.
Indiciate urgency and if you are willing to work on it either using tags or in issue text.

Issues which do not have a clear user story may not be addressed

Consensus ¶

If issue is not super obvious/straightforward, please discuss approach with the maintainers/owner and reach a consensus.

Contributions which do not have consensus with the owner may not be approved

Coding ¶

Get assigned. If you are working on issue, please tag yourself as the assignee (or ask to be tagged if you do not have privledges).

Generally:

Try to be backwards compatable to Python 3.10.
Be compatable with Numpy 2+, Pandas 2+, OSMNX 1+, PyProj 3.3+
Use PEP8 and autoformat with black
Use Google-style docstrings for all classes and methods
Test formatting and autoformat using pre-commit
Use logging
All code should have an associated test
Documentation is in the docs folder and is built using mkdocs
Additions to public API should be documented in docs/api.md
Changes to architecture should be documented in docs/architecture.md
Right now, this repo prioritizes Legibility/Simplicity >> Efficiency. That might change later.

Contributions which do not meet these requirements may not be approved

Testing and CI ¶

Tests are located in the tests folder and leverage pytest

Running tests:

pytest

Tests are automatically run when commits are pushed to Github using the .github/workflows/tests.yml workflow.

Documentation ¶

Documentation uses mkdocs and can be built by:

Install documentation requirements

pip install docs/requirements.txt

Building and serving a local copy from the GMNSpy folder

mkdocs serve

General settings for documentation can be found in mkdocs.yml

Code associated with including files and auto-generation of spec-related documentation can be found in main.py

PRs and releases will have a documentation version generated using a github workflow .github/workflows/documentation.yml using the versioning of mkdocs using mike package.

Pull Requests ¶

Use the following guidance in creating and responding to pull requests

Generally, submit PRs to the develop branch.
Keep pull requests small and focused. One issue is best.
Link Pull Requests to Issues as appropriate.
Complete the pull request template as best you can.
PRs which don’t pass the automatic checks should either address issues causing them to fail or comment as to why they aren’t.
Tag an available reviewer to review your PR.

Pull Requests which do not meet these requirements may not be approved

Review and Approval Process ¶

PRs which don’t pass the automatic checks should either address issues causing them to fail or comment as to why they aren’t.
Tag an available reviewer to review your PR.
Respond to conversation and requests

Pull Requests which do not respond to reviews may not be approved

Contributor Agreement ¶

By making any contribution to the projects, contributors self-certify to the following Contributor Agreement:

By making a contribution to this project, I certify that:

a. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

b. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

c. The contribution was provided directly to me by some other person who certified (a), (b) or © and I have not modified it.

d. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Attribution: This Contributor Agreement is adapted from the node.js project available here: https://github.com/nodejs/node/blob/main/CONTRIBUTING.md.

Contributor Covenant Code of Conduct ¶

tl;dr

give respect; get respect; or else.

Our Pledge ¶

We as GMNSpy Owners, Maintainers, and Contributors pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards ¶

Examples of behavior that contributes to a positive environment for our community include:

Demonstrating empathy and kindness toward other people
Being respectful of differing opinions, viewpoints, and experiences
Giving and gracefully accepting constructive feedback
Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

The use of sexualized language or imagery, and sexual attention or advances of any kind
Trolling, insulting or derogatory comments, and personal or political attacks
Public or private harassment
Publishing others’ private information, such as a physical or email address, without their explicit permission
Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities ¶

The community leaders for this effort include project Owner and Maintainers as described in the Contributing documentation.

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope ¶

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.

Enforcement ¶

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to @e-lo or other package maintainers.

All complaints will be reviewed and investigated promptly and fairly.

Enforcement Guidelines ¶

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction ¶

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning ¶

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban ¶

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban ¶

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution ¶

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla’s code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

Contributors ¶

Elizabeth Sall - Owner Pedro Carmago - Maintainer Ian Berg - Contributors