bcgov/bc-policy-framework-for-github

Policy information for BC Government employees using GitHub

description	tags	title
A landing page with all the information a BC Government employee would ever want to know about using GitHub as a code repository for their application.	GitHub open source code repo repository license application development guidelines	BC Gov Policy Framework For using GitHub

BC Gov Policy Framework For using GitHub

Quick Navigation Files:

Employee Guide

How To's

"Working in github.com/bcgov" Cheatsheet

BC-Policy-Framework-For-GitHub

BC Developers' Policy and Guideline Documents - All the information a BC Government employee could ever want about GitHub.

---

The BCGov GitHub Organization represents an ongoing effort to enable public & private sector developers, as well as citizen developers, the ability to collaborate on, leverage and integrate technology assets outside of the typical government procurement/contract model.

This repo's content is focused on providing information, examples and guidelines to facilitate the creation and governance of BCGov Open Source projects. We don't want to duplicate the good work GitHub has done with their own online guides. Our focus is giving BC Government people and projects the information they need to get started on GitHub while remaining compliant with BC standards and policies.

Features

The document content, templates and guides are organized into two categories ("Employee Guide" and "How To"). These are best accessed using the contents section provided under these navigation files:

Employee Guide

How To's

There is also a handy "Cheatsheet" for quick access to key policies and to-do's for BC Government people working in GitHub.

Project Status

November 2015: We have arrived at the delivery phase of the project now that we have been given sign off from the BC Government Chief Information Officer on the Employee Guide contents of this repository. That means we are starting the process of operationalizing our Org activities here on GitHub :)

Right now we are helping some early adopter projects get existing code up on GitHub. If are asking yourself "I wonder if my project code could be added to GitHub?" there is a great resource on OSS-Watch that walks you through an openness rating checklist.

If you are starting a brand new project - you came to the right place! This repo will get you going in the right direction.

The framework work items that are actively being constructed are listed

Active Stuff Here:

• BC-Gov-Org-HowTo/SAMPLE-README.md template
• BC-Open-Source-Development-Employee-Guide/Security.md
• "Working in github.com/bcgov" Cheatsheet

How to Contribute

If you would like to contribute to the guide, please see our CONTRIBUTING guideleines.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

BC Policy Framework For GitHub by the Province of British Columbia is licensed under a Creative Commons Attribution 4.0 International License.

bc-policy-framework-for-github's Issues

Devhub Issue: Approaches to Collaborating/Contributing no description front matter

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/Collaborating-Contributing.md
(do not delete) devhub page: https://developer.gov.bc.ca/Code-Management/Approaches-to-CollaboratingContributing

Devhub Content Issue

There is no description front matter for this document. A 140 character (or less) description should be used to improve the ux/ui of this document as it appears within the Devhub

Devhub Issue: Beginner Guide to Developing on the Platform [Broken links]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/README.md
(do not delete) devhub page: https://developer.gov.bc.ca/Beginner-Guide-to-Developing-on-the-Platform/BC-Gov-Policy-Framework-For-using-GitHub

Devhub Content Issue

Broken links:

Error	URL	Anchor Text	Linked From
404 Not Found	https://github.com/BC-Open-Source-Development-Employee-Guide/README.md	Employee Guide	https://developer.gov.bc.ca/BC-Gov-Policy-Framework-For-using-GitHub
404 Not Found	https://github.com/BC-Gov-Org-HowTo/README.md	How To's	https://developer.gov.bc.ca/BC-Gov-Policy-Framework-For-using-GitHub
404 Not Found	https://github.com/BC-Gov-Org-HowTo/Cheatsheet.md	"Working in github.com/bcgov" Cheatsheet	https://developer.gov.bc.ca/BC-Gov-Policy-Framework-For-using-GitHub

Alternative Contact?

The email address provided in the Employee Guide is no longer valid. Is there an alternate contact that could be listed?

Do we submit the Open Content Assessment checklist anywhere?

I am ready to create a new repository and I have everything on the Open Content Assessment Checklist checked off, except for the DM (or delegate) signature. Before I submit that for DM approval, just would like to know if we need to submit the signed checklist anywhere or if we need to put it on the repository etc. ?

Thanks!

Devhub Issue: Github Practices in Gov [Using Licenses Link Broken]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/appropriate-use.md
(do not delete) devhub page: http://0.0.0.0:8000/Code-Management/Github-Practices-in-Gov/

Devhub Content Issue

The link to Using Licences is Broken, this file does not exist anymore!

Devhub Issue: Github Practices in Gov — file name CODE_OF_CONDUCT.md is not displayed as it should be

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/appropriate-use.md
(do not delete) devhub page: https://developer.gov.bc.ca/Code-Management/Github-Practices-in-Gov

Devhub Content Issue

The underscore character (_) makes the name of the file CODE_OF_CONDUCT.md appears as CODEOFCONDUCT.md on the web page. We can fix this by escaping both underscores from the file name.

Todd's test backlog item

I want to test rapid adoption

Add project lifecycle badge

No Project Lifecycle Badge found in your readme!

Hello! I scanned your readme and could not find a project lifecycle badge. A project lifecycle badge will provide contributors to your project as well as other stakeholders (platform services, executive) insight into the lifecycle of your repository.

What is a Project Lifecycle Badge?

It is a simple image that neatly describes your project's stage in its lifecycle. More information can be found in the project lifecycle badges documentation.

What do I need to do?

I suggest you make a PR into your README.md and add a project lifecycle badge near the top where it is easy for your users to pick it up :). Once it is merged feel free to close this issue. I will not open up a new one :)

off boarding content?

It would be useful imo for the bc-policy-framework-for-github to include a section or .md file on off boarding guidance.

e.g.

• when+how to revoke org level membership (or if at all/ever?)
• how to give some access as a collaborator if they are no longer a bcgov member and it is warranted
• ensuring all repos have a maintainer when someone leaves the bcgov GitHub org
• who is responsible for off boarding and by when
• ....

markdown headers rendering as a table at the top of all files

Many/most of the .md files have a header section that renders as a large table in html.

If the behaviour is intentional, then this issue should be closed. If not, then I think the metadata can be captured in a way where the information does not render at the top of each html page—which makes the reader have to scroll quite a ways to get to the page content.

How to deal with a partial PR?

In my experience dealing with PRs on my open source projects is that the majority of PRs will be partially implemented/working. I'd be curious how this could be dealt with in respect to the bounty. Ideally, we find a way for people to work together on solutions rather than duplicating efforts. Thoughts?

Devhub Issue: Github Practices in Gov Update Social Media Guidelines link

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/appropriate-use.md
(do not delete) devhub page: /Github-Practices-in-Gov

Devhub Content Issue

• When you use any of the social media features of GitHub, making comments, forum posts please refer to the Social Media Guidelines for appropriate conduct online.

This link http://www.gov.bc.ca/citz/citizens_engagement/some_guidelines_master.pdf redirects to https://www2.gov.bc.ca/gov/content/governments/organizational-structure/ministries-organizations/ministries/citizens-services
I found this link https://www2.gov.bc.ca/gov/content/governments/services-for-government/policies-procedures/social-media-guidelines
but not sure if this page applies to Github, as there is no mention of Github best practices. Also as clarification does this also include pull requests and code reviews.

Also on the https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/31300dd4ac9b6b143c94b868dde9880bf5655bfc/CODE_OF_CONDUCT.md you might want to update the email address, as I'm pretty sure Todd Wilson is no longer the contact.

Accepting Community Contributions to Government Repositories

Feature: Accepting Community Contributions to Government Repositories
  As a private citizen
  In order to participate in the open source community
  I would like to voluntarily contribute my code to an official bcgov project

  Scenario:
    Given publicly available source code on github
    When I fork a repository from bcgov
    And I commit code in my forked repository
    And I send a pull request to the upstream bcgov project repository
    And the pull request contribution contains a valuable improvement to the upstream
    Then I would like my contribution to be merged upstream
    And I should accept that my contribution will be redistributed under the terms of the upstream license
    And I should accept that my contribution includes patches to code
    And I should accept that my contribution includes a public record of my name
    And I should accept that my contribution includes a public record of my email

As maintainers, we might require citizens to e-sign a Contributor License Agreement (CLA) before merging their changes, or we might include a Developer Certificate of Origin (DCO) in the repository they're merging to. In the CLA vs DCO decision some evaluation of the minimum documentation of citizen consent required would be helpful. A DCO is might lighter-weight and the process officially adopted by the Linux Foundation, so a good place to start might be to evaluate the suitability of that approach before evaluating a CLA.

Consider link for python security? (discussion)

Not sure if this is the best reference, but putting this out for discussion:
https://devguide.python.org/documenting/#security-considerations-and-other-concerns

If it's helpful it could be included in the list on https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/Security.md

Devhub Issue: Github Practices in Gov image link in frontmatter can't be svg

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/appropriate-use.md
(do not delete) devhub page: /Github-Practices-in-Gov

Devhub Content Issue

the svg file referenced in the image frontmatter is not referencable from outside github. we should replace this with a png file.

Broken Github links

Hi, I noticed a number of you "how-to" steps for Github are giving a 404 error.
These include:

1. https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Gov-Org-HowTo/Creating-And-Deleting-Repos.md
2. https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Gov-Org-HowTo/using-licenses.md

Thanks, Gen

Devhub Issue: Github Practices in Gov [ Needs a better title]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Open-Source-Development-Employee-Guide/appropriate-use.md
(do not delete) devhub page: https://developer.gov.bc.ca/Code-Management/Github-Practices-in-Gov

Devhub Content Issue

This content has a title 'Appropriate Use', we should have a title that says "github practices in gov ' or something of the like

Feedback on Pay for Pull

I am opening this issue as a central place to discuss / give feedback on the Pay for Pull initiative http://blog.data.gov.bc.ca/2016/01/pay-for-pull/

Devhub Issue: BC Gov Policy Framework For using GitHub [links broken]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/README.md
(do not delete) devhub page: /BC-Gov-Policy-Framework-For-using-GitHub

Devhub Content Issue

the links here are broken. also missing some docs in this repo

Add missing topics

TL;DR

Topics greatly improve the discoverability of repos; please add the short code from the table below to the topics of your repo so that ministries can use GitHub's search to find out what repos belong to them and other visitors can find useful content (and reuse it!).

Why Topic

In short order we'll add our 800th repo. This large number clearly demonstrates the success of using GitHub and our Open Source initiative. This huge success means its critical that we work to make our content as discoverable as possible; Through discoverability, we promote code reuse across a large decentralized organization like the Government of British Columbia as well as allow ministries to find the repos they own.

What to do

Below is a table of abbreviation a.k.a short codes for each ministry; they're the ones used in all @gov.bc.ca email addresses. Please add the short codes of the ministry or organization that "owns" this repo as a topic.

That's in, you're done!!!

How to use

Once topics are added, you can use them in GitHub's search. For example, enter something like org:bcgov topic:citz to find all the repos that belong to Citizens' Services. You can refine this search by adding key words specific to a subject you're interested in. To learn more about searching through repos check out GitHub's doc on searching.

Pro Tip 🤓

• If your org is not in the list below, or the table contains errors, please create an issue here.

• While you're doing this, add additional topics that would help someone searching for "something". These can be the language used javascript or R; something like opendata or data for data only repos; or any other key words that are useful.

• Add a meaningful description to your repo. This is hugely valuable to people looking through our repositories.

• If your application is live, add the production URL.

Ministry Short Codes

Short Code	Organization Name
AEST	Advanced Education, Skills & Training
AGRI	Agriculture
ALC	Agriculture Land Commission
AG	Attorney General
MCF	Children & Family Development
CITZ	Citizens' Services
DBC	Destination BC
EMBC	Emergency Management BC
EAO	Environmental Assessment Office
EDUC	Education
EMPR	Energy, Mines & Petroleum Resources
ENV	Environment & Climate Change Strategy
FIN	Finance
FLNR	Forests, Lands, Natural Resource Operations & Rural Development
HLTH	Health
FLNR	Indigenous Relations & Reconciliation
JEDC	Jobs, Economic Development & Competitiveness
LBR	Labour Policy & Legislation
LDB	BC Liquor Distribution Branch
MMHA	Mental Health & Addictions
MAH	Municipal Affairs & Housing
BCPC	Pension Corporation
PSA	Public Safety & Solicitor General & Emergency B.C.
SDPR	Social Development & Poverty Reduction
TCA	Tourism, Arts & Culture
TRAN	Transportation & Infrastructure

NOTE See an error or omission? Please create an issue here to get it remedied.

Devhub Issue: BC Gov Policy Framework For using GitHub [short description here]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/README.md
(do not delete) devhub page: /BC-Gov-Policy-Framework-For-using-GitHub

Devhub Content Issue

Broken link: https://github.com/BC-Gov-Org-HowTo/Cheatsheet.md

Returns a 404

Provide recommended/sample .gitignore

Like how there is a sample readme, code of conduct, and contributing file, is there any appetite for including a sample or recommended gitignore?

At a minimum I was envisioning a link to github/gitignore and an in-line sample of a gitignore that excludes secrets by file type.

Devhub Issue: BC Gov Policy Framework For using GitHub [short description here]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/README.md
(do not delete) devhub page: /BC-Gov-Policy-Framework-For-using-GitHub

Devhub Content Issue

The description of bcgov-c indicates it is "for the product teams private repos with closed source code and private docs."
Source: https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/31300dd4ac9b6b143c94b868dde9880bf5655bfc/github/README.md#bcgov-c-org

If you review the content of https://github.com/bcgov-c from an unauthenticated session there are five "Public" repos visible:

• https://github.com/bcgov-c/tenant-gitops-ea352d
• https://github.com/bcgov-c/wally
• https://github.com/bcgov-c/RTB-Dispute-Management-System
• https://github.com/bcgov-c/bcgov-terraform-module-template
• https://github.com/bcgov-c/pipeline-demo-app

Add project lifecycle badge

No Project Lifecycle Badge found in your readme!

Hello! I scanned your readme and could not find a project lifecycle badge. A project lifecycle badge will provide contributors to your project as well as other stakeholders (platform services, executive) insight into the lifecycle of your repository.

What is a Project Lifecycle Badge?

It is a simple image that neatly describes your project's stage in its lifecycle. More information can be found in the project lifecycle badges documentation.

What do I need to do?

I suggest you make a PR into your README.md and add a project lifecycle badge near the top where it is easy for your users to pick it up :). Once it is merged feel free to close this issue. I will not open up a new one :)

Approval Checklist

The approval checklist was constructed based on experience with opening government data sets. That process is more of a publishing exercise - whereas developing on Github is a creative process.

We are revisiting the approval checklist in the new year to move forward on simplifying and regularizing open source development at the BCGov.

Add a Repo Setup Guide to the github docs

As discussed in #34 we should have some documentation that talks about some best practices with repo setup in github. Thiings like protecting master, enforcing code reviews as well as ensuring PR's are up to date with master (by a rebase or other means) prior to pulling

Ideally a repo provisioning service that accomplished most if not all of this would be even better.

Add a "How To" for signing commits and releases

Devhub Issue: Beginner Guide to Developing on the Platform [short description here]

path: (do not delete) https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/README.md
(do not delete) devhub page: https://developer.gov.bc.ca/Beginner-Guide-to-Developing-on-the-Platform/BC-Gov-Policy-Framework-For-using-GitHub

Devhub Content Issue

some of the links on this page are broken and yield 404s

Spelling error

This sentence has a typo in the word "Guidline" :) in the readme.
BC Developers' Policy and Guidline Documents - All the information a BC Gvt employee could ever want about GitHub