Skip to content

Latest commit

 

History

History
112 lines (78 loc) · 4.46 KB

README.md

File metadata and controls

112 lines (78 loc) · 4.46 KB
Raw

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.