Development

Development Environment

If you plan on developing and changing code within the projectcard project, you will likely want to set up your own development environment from a cloned fork.

Helpful prerequisites:

• github desktop
• conda
• VS Code (or another IDE)

Fork and Install:

1. Fork and clone repo locally

   gh cligithub ux

   gh repo fork network-wrangler/projectcard --clone=true
   cd projectcard
   git remote add upstream https://github.com/network-wrangler/projectcard.git
   

   • In browser, fork the repository to your github account: https://github.com/network-wrangler/projectcard/fork.
   • In the browser with your new fork, click green code botton and clone to local disk using Github Desktop.
   • Add the original repo to your upstream remotes to be able to track changes:
   • Make sure the cloned repository is open in GitHub Desktop
   • Click on Repository in the menu bar
   • Select Open in Terminal (or Open in Git Bash on Windows).
   • In the terminal window that opens, enter the following command to add the original repository as a remote named upstream:

     git remote add upstream https://github.com/network-wrangler/projectcard.git
     

2. Install dependencies

   conda (recommended)pip

   conda install --yes --file requirements.txt
   

   pip install -r requirements.txt
   

3. Install from working directory

   pip install -e .
   

Keeping your fork updated

To make sure any development and work you are doing takes advantage of and is compatable with the main projectcard repository, you will want to fetch and merge updates.

Using Github DesktopIn terminal

Click on Fetch origin in the top bar of GitHub Desktop to fetch the latest changes from your fork.

Open the repository in the terminal and run the following command to fetch updates from the upstream repository and merge the udpates into your local branch.

git fetch upstream
git merge upstream/main

Replace main with the branch of the repository you want to develop towards if it is different.

Style Guide

• All public modules and functions should be documented using google-style docstrings.
• Public modules should be documented with usage examples.
• Public functions should be covered by a test, located in the /tests folder.
• Code should be formatted per the ruff implementation of PEP8 (which is like black, but faster)
• Line width should be no more than 99 characters.
• Document function signatures with type annotations and pass inspection with mypy

To make sure your code conforms to our style – ensuring that all differences are meaningful and not just fommatting – please use pre-commit before submitting any pull-requests to the main repository:

pre-commit run --all-files

This will make sure your code conforms to our guidelines as defined in pyproject.toml.

Contributing

Generally we are happy to accept pull-requests directly to the main branch which improve documentation or make very minor changes. If you are making more significant changes, please:

Before starting

• Create an issue describing the problem you ar solving: Make sure people know what you are working on and that they can let you know sooner rather than later about their opinions (or assign yourself an existing issue).

Developing

• Follow the style guide
• Regularly update your fork with upstream changes

Incorporating Code to main ProjectCard Repository

• Make sure your code passes all tests
• If you updated documentation, make [sure it properly builds].
• Run pre-commit
• Submit a pull-request to the main project card repository and thoroughly describe the problem you are trying to solve, referencing the issue it addresses
• Respond to requests from the code reviewer

Documentation

Documentation is maintained in the /docs repository in markdown text files and is built using the mkdocs package. Public documentation is built using a Github Workflow (.github/workflows/push.yml) and published using mike to Github Pages.

Build the documentation locally

This is useful to make sure that changes you made are rendered as you would expect them.

install documentation dependencies

pip -r docs/requirements.txt

building documentation locally

mkdocs serve

Releases

• Releases follow semantic versioning.
• Releases are triggered by project management team via the github “releases” interface.
• Creating a release in github will trigger a github action to send it to pypi so that users installing it via pip will have access to it.

Tip

Releases must have a unique version number in order to be updated on pypi.

Changelog

Notable changes and version history.

Version	Date	Comment
v0.3.3	2024-10-15	Fixed “all” being treated as a str enum instead of bool in some places.
v0.3.2	2024-10-09	Fix bug with pycode validation and use Ruff instead of Flake8 b/c of deprecated API.
v0.3.1	2024-10-07	Improved resilience of read_cards() including ability to handle relative paths.
v0.3.0	2024-09-27	Added transit addition and deletion change types.
v0.2.0	2024-09-08	Read cards from nested folders.
v0.1.2	2024-08-05	-
v0.1.1	2024-06-20	Initial release on PyPI