.github Bridge (docs) update #5

MitchellShiell · 2024-10-22T21:20:58Z

This repository contains organization-wide GitHub configurations and community health files for the Overture project. These files serve as default community health files for all Overture repositories that don't have their own specific versions.

I am also putting our documentation standards content here in the /standards folder and rendered out to the docs site here (.github is a submodule within the future OvertureDev repo)

Repository Structure

The repository is organized with the following structure:

.
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   ├── feature_request.md
│   └── custom_template.md
├── workflows/
├── profile/
├── Standards/
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── CODEOWNERS
├── FUNDING.yml
├── PULL_REQUEST_TEMPLATE.md
├── README.md
└── ROADMAP.md

ISSUE_TEMPLATE/: Contains templates for different types of issues.
workflows/: Can hold GitHub Actions workflow files for CI/CD.
profile/: Contains the files used for the organization landing page readme found on https://github.com/overture-stack.
Standards/: Includes organizational documentation standards and guidelines.
All Root-level files are community health files and GitHub-specific templates.
- These will serve as default files for all Overture repositories that don't have their own versions.

standards/04-community.md

justincorrigible · 2024-11-13T19:45:40Z

standards/04-community.md

+- `main` is for stable production code
+- `develop` is the integration branch for new features


TODO: update these to main and release (Note to self)

justincorrigible · 2024-11-13T19:47:27Z

standards/04-community.md

+<summary>**Click here for our code of conduct page**</summary>
+
+``````
+# Code of Conduct


isn't this the same one in the code of conduct file? should this be a link to that instead of duplicating the text? alternatively, that file could link to this content here.

Idea is having them templated and available for reproducibility, if you look at it on the doc site its a page that just has all the relevant community resources in an easy to copy paste manner

MitchellShiell · 2024-11-13T20:42:02Z

Just noticed this repo is unprotected, not sure if intentional

justincorrigible · 2024-11-25T19:38:32Z

standards/02-Software/02-Docs/images/platform.svg

This is how the svg is displayed here... may be a glitch that carries over into others' display?

Displays fine everywhere for me (I'm using chrome)

justincorrigible · 2024-11-25T19:41:33Z

ISSUE_TEMPLATE/custom_template.md

@@ -0,0 +1 @@
+


placeholder?

This allows people to make an issue without any templating, serves any possible edge case outside of your feature request and bug templates

FUNDING.yml

justincorrigible · 2024-11-25T19:43:44Z

CODEOWNERS.txt

@@ -0,0 +1,81 @@
+# If we choose to use the codeowners functionality update the file as a .md then uncomment and update the following:


This comment makes me think this is meant more as a template than as an org-wide article?

which leads me to ask both what the original source if the template is, and are there instructions anywhere on what these templates are for? e.g. "when creating a new repo you will find these X and Y and Z files, which are used in the following scenarios..." etc.

do we have that somewhere I've missed?

Briefly explained here: https://docs.overture.bio/docs/standards/github#codeowners

This is completely optional if you don't want it than we can remove it just wanted to offer all that is possible

justincorrigible · 2024-11-25T19:51:45Z

CODE_OF_CONDUCT.md

+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[this email]([email protected]).


wonder whether we should have a different email for this (which of course gets redirected to this same one under the hood). the purpose being to make it seem like there's more/different people handling this, hoping to bolster legitimacy beyond a single catch-all bucket

No need, even in the event that is the case contact emails can route to multiple people

PULL_REQUEST_TEMPLATE.md

justincorrigible · 2024-11-26T19:09:21Z

README.md


-This repo hosts a few templates to be applied across all repos in this organisation.
-It also holds the organisation's profile, which is public to everyone.
+This repository contains organization-wide GitHub configurations and community health files for the Overture project. These files serve as default community health files for all Overture repositories that don't have their own specific versions.


I've noticed a few "code of conduct" files in other repos. Do those need "specific versions" of that? I think they can be removed from there.

agreed and updating now

justincorrigible · 2024-11-26T19:13:09Z

README.md

+- `ISSUE_TEMPLATE/`: Contains templates for different types of issues.
+- `workflows/`: Can hold GitHub Actions workflow files for CI/CD.
+- `profile/`: Contains the files used for the organization landing page readme found on https://github.com/overture-stack.
+- `Standards/`: Includes organizational documentation standards and guidelines.


I've noticed in other repos these bullet points have initial capitals here regardless of the actual casing of the folder above. this should be consistent everywhere.

... and to be clear, I mean the bullets, not the folders themselves

capitalization are reflective of actual casing of the folder/file referenced "`` " is enough to reflect that

justincorrigible · 2024-11-26T19:14:48Z

README.md

+- `profile/`: Contains the files used for the organization landing page readme found on https://github.com/overture-stack.
+- `Standards/`: Includes organizational documentation standards and guidelines.
+- All Root-level files are community health files and GitHub-specific templates.
+    - These will serve as default files for all Overture repositories that don't have their own versions.


justincorrigible · 2024-11-26T19:18:28Z

standards/01-github.md

this seems like a document for us to create organisations or repos, not for other people to read about Overture... but perhaps I'm misreading it? I guess I'm not clear on what the purpose for this one is here.

Standards can be applied to other projects that use Overture (PCGL), it's just a nice value add also a marker of the health of the project

standards/02-Software/02-Docs/03-Usage.md

Co-authored-by: Anders Richardsson <[email protected]>

justincorrigible · 2024-12-02T21:54:15Z

profile/portal-services.webp

was ist das? 🤔

Optional Image for profile page,

justincorrigible · 2024-12-03T13:54:08Z

standards/02-Software/02-software.mdx

+
+The active voice is concise and more accessible for readers to comprehend. Active voice is naturally used in conversation and therefore, readers understand and engage more with writing in the active voice.
+
+| 👎 Disengaging| 👍 Engaging|


standards/02-Software/02-software.mdx

justincorrigible · 2024-12-03T13:57:15Z

standards/02-Software/05-Contribute.md

lol which one is it, then? "contribute", "contribution" or "contributing"?

@justincorrigible this file contains the "old" branch model. needs updates once we finish switching over to the "new" one.

Any and all works

justincorrigible · 2024-12-03T13:57:57Z

standards/02-Software/05-Contribute.md

+Ensure all links correctly resolve and names and content are updated based on your project needs. Use the `CONTRIBUTING.md` copy here to get you started:
+
+<details>
+  <summary><b>Click here for a copy of our contributing.md</b></summary>


Should this one be in full caps too, to keep things consistent?

justincorrigible · 2024-12-03T14:04:03Z

standards/02-Software/05-Contribute.md

+- `main` is for stable production code
+- `develop` is the integration branch for new features
+- `feature/<name>` for feature branches
+- `release/v<version>` for release branches
+- `hotfix/<name>` for hotfix branches


Note to self @justincorrigible:
Update this!

justincorrigible · 2024-12-03T14:06:56Z

standards/02-Software/05-Contribute.md

+- `main` is for stable production code
+- `develop` is the integration branch for new features
+- `feature/<name>` for feature branches
+- `release/v<version>` for release branches
+- `hotfix/<name>` for hotfix branches


@justincorrigible here too

Co-authored-by: Anders Richardsson <[email protected]>

…eeded

MitchellShiell added 7 commits October 9, 2024 10:47

bridge documentation update

99fca86

updated project doc apge

3092cb6

removeed buttons on projects page

784c89d

minor typo

a954316

updated contribution section

2a539f0

minor

d974d06

updated readme template

bbfeedb

MitchellShiell mentioned this pull request Oct 22, 2024

🎻 Conductor overture-stack/conductor#20

Merged

MitchellShiell added 3 commits October 31, 2024 11:22

links

e1675a8

updated bridge doc page

33f9cc8

updated standards doc

1338169

MitchellShiell mentioned this pull request Nov 1, 2024

Deployment Checklist overture-stack/docs#10

Open

29 tasks

MitchellShiell added 3 commits November 2, 2024 19:22

minor update

60c5ab1

cleanup + updated readme

fc0dde9

minor typo

66a56c5

MitchellShiell changed the title ~~[WIP] - .github for Dev Doc Site~~ .github Bridge (docs) update Nov 13, 2024

MitchellShiell requested a review from justincorrigible November 13, 2024 17:50

MitchellShiell marked this pull request as ready for review November 13, 2024 17:50

Merge branch 'master' into bridgeGitHub

3d49749

MitchellShiell added the documentation Help docs are needed for this/writing docs needed label Nov 13, 2024

justincorrigible reviewed Nov 13, 2024

View reviewed changes

standards/04-community.md Show resolved Hide resolved

justincorrigible reviewed Nov 13, 2024

View reviewed changes

standards/04-community.md Show resolved Hide resolved

justincorrigible reviewed Nov 13, 2024

View reviewed changes

MitchellShiell added 2 commits November 25, 2024 10:34

netlify link

9a5a917

updated cross referenced urls to docs.overture.bio

4722364

MitchellShiell requested a review from justincorrigible November 25, 2024 17:26

justincorrigible reviewed Nov 25, 2024

View reviewed changes

FUNDING.yml Outdated Show resolved Hide resolved

justincorrigible reviewed Nov 25, 2024

View reviewed changes

PULL_REQUEST_TEMPLATE.md Outdated Show resolved Hide resolved

justincorrigible reviewed Nov 25, 2024

View reviewed changes

PULL_REQUEST_TEMPLATE.md Outdated Show resolved Hide resolved

justincorrigible reviewed Nov 26, 2024

View reviewed changes

standards/02-Software/02-Docs/03-Usage.md Outdated Show resolved Hide resolved

MitchellShiell and others added 4 commits November 26, 2024 16:29

Update FUNDING.yml

5d267a6

Co-authored-by: Anders Richardsson <[email protected]>

Update standards/02-Software/02-Docs/03-Usage.md

214eeba

Co-authored-by: Anders Richardsson <[email protected]>

Update PULL_REQUEST_TEMPLATE.md

6f4c7f5

Co-authored-by: Anders Richardsson <[email protected]>

Update PULL_REQUEST_TEMPLATE.md

a4d8aee

Co-authored-by: Anders Richardsson <[email protected]>

justincorrigible reviewed Dec 2, 2024

View reviewed changes

justincorrigible reviewed Dec 3, 2024

View reviewed changes

standards/02-Software/02-software.mdx Outdated Show resolved Hide resolved

justincorrigible reviewed Dec 3, 2024

View reviewed changes

MitchellShiell and others added 2 commits December 3, 2024 10:27

Update standards/02-Software/02-software.mdx

e59b6c1

Co-authored-by: Anders Richardsson <[email protected]>

fixed typos in images, reduced image size to ~1mb will try lower if n…

7f96a50

…eeded

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.github Bridge (docs) update #5

.github Bridge (docs) update #5

MitchellShiell commented Oct 22, 2024

justincorrigible Nov 13, 2024

justincorrigible Nov 13, 2024 •

edited

Loading

MitchellShiell Nov 13, 2024 •

edited

Loading

MitchellShiell commented Nov 13, 2024 •

edited

Loading

justincorrigible Nov 25, 2024

MitchellShiell Nov 26, 2024

justincorrigible Nov 25, 2024

MitchellShiell Nov 26, 2024

justincorrigible Nov 25, 2024

justincorrigible Nov 25, 2024 •

edited

Loading

MitchellShiell Nov 26, 2024

MitchellShiell Nov 26, 2024

justincorrigible Nov 25, 2024

MitchellShiell Nov 26, 2024

justincorrigible Nov 26, 2024

MitchellShiell Nov 26, 2024

justincorrigible Nov 26, 2024 •

edited

Loading

MitchellShiell Nov 26, 2024 •

edited

Loading

justincorrigible Nov 26, 2024

justincorrigible Nov 26, 2024

MitchellShiell Nov 26, 2024

justincorrigible Dec 2, 2024

MitchellShiell Dec 2, 2024

justincorrigible Dec 3, 2024

justincorrigible Dec 3, 2024

justincorrigible Dec 3, 2024

MitchellShiell Dec 3, 2024

justincorrigible Dec 3, 2024

justincorrigible Dec 3, 2024

justincorrigible Dec 3, 2024

		- `main` is for stable production code
		- `develop` is the integration branch for new features

		@@ -0,0 +1,81 @@
		# If we choose to use the codeowners functionality update the file as a .md then uncomment and update the following:


		The active voice is concise and more accessible for readers to comprehend. Active voice is naturally used in conversation and therefore, readers understand and engage more with writing in the active voice.

		\| 👎 Disengaging\| 👍 Engaging\|

	\| 👎 Disengaging\| 👍 Engaging\|
	\| 👎 Disengaging \| 👍 Engaging \|

.github Bridge (docs) update #5

Are you sure you want to change the base?

.github Bridge (docs) update #5

Conversation

MitchellShiell commented Oct 22, 2024

Repository Structure

Choose a reason for hiding this comment

justincorrigible Nov 13, 2024 • edited Loading

Choose a reason for hiding this comment

MitchellShiell Nov 13, 2024 • edited Loading

Choose a reason for hiding this comment

MitchellShiell commented Nov 13, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

justincorrigible Nov 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

justincorrigible Nov 26, 2024 • edited Loading

Choose a reason for hiding this comment

MitchellShiell Nov 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

justincorrigible Nov 13, 2024 •

edited

Loading

MitchellShiell Nov 13, 2024 •

edited

Loading

MitchellShiell commented Nov 13, 2024 •

edited

Loading

justincorrigible Nov 25, 2024 •

edited

Loading

justincorrigible Nov 26, 2024 •

edited

Loading

MitchellShiell Nov 26, 2024 •

edited

Loading