Skip to main content

Tool for uploading project boards to GitHub

Project description

Tool for uploading project boards on GitHub

GitHub GitHub Open Issues Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. Sphinx PyPI DOI

The package ghproject is a tool for uploading project boards to GitHub filled with labelled issues. This has been created to aid project management in research software projects on GitHub.

Possible use cases:

  • Create an onboarding project board for new team members
  • Create a project board for developing FAIR research software

Navigate to API documentation for more detailed and structured information.

Documentation for users

Installation

The tool can be installed with pip:

pip install ghproject

Using ghproject requires a GitHub Personal Access Token (PAT), which can be created via your GitHub settings. To prevent hardcoding of any access tokens, it's a best practice to keep your GitHub PAT as a local environment variable. By default, the package will inspect the environment variable GITHUB_TOKEN for the argument --token.

To set up the Token called GITHUB_TOKEN for Windows, execute in a terminal:

setx GITHUB_TOKEN <token> 

You might need to restart your terminal/IDE for the changes to take effect.

Usage

The tool can be used both from the command line and from a Python interpretor, e.g. a Jupyter notebook. We take as an example the following use case in which we want to upload a project board with accompanying issues. Issues are generated from markdown files that need to contain a header with the issue title and associated labels (as a list of strings).

---
title: Create FAIR software checklist
labels: ["documentation", "feature"]
---

The issue body is then created from the following markdown text. Examples of issues can be found in the folder /md_files in the repository.

You can call the module to upload a new project to a GitHub reposotory from the command line. Use to following command to view the help file:

python -m  ghproject.upload_project -h

For example, the following command will create the project board "My project" in the repository "my_repository" and add the issues generated from the markdown files in the relative folder "/md_files":

python -m ghproject.upload_project --repo "my_repository" --owner "username" --path "./md_files" --project "My project"

The various functions can also be accessed directly from the GitHubAPI class. Example usage would be:

import os
from ghproject import GitHubAPI

# Setup arguments
repo_name = "my_repository"
repo_owner = "username" # Github user name or organization name
token = os.environ["GITHUB_TOKEN"]
path_issues = "./md_files"
project_name = "My project"

repo = GitHubAPI(repo_name, repo_owner, token)
repo.load_markdown_files(path_issues)
repo.push_project(project_name)
repo.push_issues()
repo.add_issues_to_project(project_name)

Documentation for developers

Installation

I recommend installing the tool inside a conda environment:

git clone https://github.com/mwakok/ghproject.git
cd ghproject
conda env create -f environment.yml
conda activate env_ghproject
pip install -e .[dev]

License

Copyright (c) 2022, Maurits Kok

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ghproject-0.0.2.tar.gz (13.7 kB view details)

Uploaded Source

Built Distribution

ghproject-0.0.2-py3-none-any.whl (14.0 kB view details)

Uploaded Python 3

File details

Details for the file ghproject-0.0.2.tar.gz.

File metadata

  • Download URL: ghproject-0.0.2.tar.gz
  • Upload date:
  • Size: 13.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.7.1 importlib_metadata/4.10.0 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for ghproject-0.0.2.tar.gz
Algorithm Hash digest
SHA256 076f86808015ca9921c8504b2d96ecbe8193dc6fe9a8389580d5d554a4f5800b
MD5 6fd0ecaa035caa62dafd899ec75f7f75
BLAKE2b-256 780dd71b4ac790d92e39cb6f3c9742ed4a7ba1ee29131eb073d95fc80a8fc613

See more details on using hashes here.

File details

Details for the file ghproject-0.0.2-py3-none-any.whl.

File metadata

  • Download URL: ghproject-0.0.2-py3-none-any.whl
  • Upload date:
  • Size: 14.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.7.1 importlib_metadata/4.10.0 pkginfo/1.8.2 requests/2.27.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for ghproject-0.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 ae593d1e8a12b74d1b89d1a37a121ee339d2077077e19caa9f44f28b9e46a104
MD5 e9613131cd3551c01284fa092b6ae3d7
BLAKE2b-256 7d04de8a8e3cf32728b644d6aaf35e4c158bab6610e3ff573decb134c9954aec

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page