Create a meta .github repo for the Silverstripe organisation

GuySartorelli commented 2 years ago

Currently each repository has its own meta files such as "CONTRIBUTING", "SECURITY" etc which are (or should be) identical - or those may be missing entirely. There's no standard or any process for updating them. Ideally those should be standard and all point to the relevant docs.

A .github repository allows us to have default meta files.
It also allows us to have a README.md file at the organisation level (see Laravel's repo as an example) which will display on https://github.com/silverstripe. We can use this to give a general overview of Silverstripe CMS, how to get started, how to contribute, etc.
Finally, it can be used as a centralised space for conversations that don't really apply to any given repository. Historically those discussions have been held in the silverstripe/silverstripe-framework repository.

Acceptance Criteria

[x] A new .github repository exists
[x] An organisation-level README.md file exists with some helpful information
[x] Appropriate default meta files have been created
[ ] The existing meta files in individual repos are removed, so that the default files can apply
[x] Validate that we are using the BSD-3 on all repos except docs.
[x] Only applies to the Silverstripe organisation NOT symbiote, bringyourownideas, etc

PRs

The following don't have creative-commoners forks, though don't really seem appropriate to even have LICENSE files in them

gatsby-poc
nextjs-poc
nextjs-poc-backend
one-ring-rentals
platform-status-page
silverstripe-nextjs-starter
silverstripe-elemental-layoutblock
silverstripe-ux

GuySartorelli commented 1 year ago

https://github.com/silverstripe/.github

emteknetnz commented 1 year ago

For INITIAL PEER REVIEW - this is my proposed approach - please let me know if you agree / disagree / would change bits

Methods of updating files in repos

Update .github templates so that NEW modules get a default set of meta files
Update EXISTING modules on the default branch only so that they're consistent using a script to update all the modules - repurpose this thing - https://github.com/emteknetnz/module-standardiser/blob/main/run.php that was used to do things like bulk update the supported module badges in all the README.md's

Because we need to do 2. to meet the AC's of this card, I think it makes sense to expand the scope of this card a bit to do more stuff "while we're at it"

Meta files to update in all repos

Do update / overwrite (these will also be added as templates in .github)

.editorconfig - this should be the same for all repos - no big deal they include instructions for formatting JS files even if there are no JS files in the repo
SUPPORT.md - Says "do not use github for support", and instead directs people to primarily to community slack also forums.
CONTRIBUTING.md - Includes a link to https://docs.silverstripe.org/en/5/contributing/code/. Also details what the process is for disclosing security things is. I do NOT think we need a separate SECURITY.md for this - symfony includes a security link it their CONTRIBUTING.md - https://github.com/symfony/symfony/blob/6.4/CONTRIBUTING.md

Add if they don't already exist (these will also be added as templates in .github)

LICENSE - BUT only add if there isn't already an existing license there. We need to be careful of existing licenses because they may contain authors who we definitely must not remove e.g. https://github.com/silverstripe/silverstripe-mfa/blob/5/LICENSE.md. There may also be some consequences to changing an existing license to a different one (I know little about this) Note - our convention is mostly to omit the .md extension - which I think is correct we shouldn't have markdown in here anyway, is more of a txt file. We'll need to scan somehow to see if any existing LICENSE's are non BSD-3 and if there are any deal with those on a case by case.

Remove if they exist

Files for any third party services that are no longer used e.g. .codeclimate.yml, .scrutinizer.yml, etc
changelog.md - likely to be hopelessly out of date e.g. - https://github.com/silverstripe/silverstripe-asset-admin/blob/2/changelog.md
Anything else identified as redundant while scanning all the repos

Do not update

README.md - leave these as they are since they're custom for each repo. One exception to this is silverstripe/framework which contains out of date info for support etc - remove this content
Linting files - sass-lint.yml, .eslintignore, phpcs.xml.dist, etc - these only make sense if they are the corresponding file with appropriate extensions in the repo. While I'd like to standardise these where appropriate, it will break linting in CI in many cases and is really outside the scope of work for this card.

GuySartorelli commented 1 year ago

You haven't mentioned an organisation-level README in your breakdown above. Are you implying by omission that we shouldn't have one, or do you consider this a step to be done after the above, or....?

Methods of updating files in repos - "Because we need to do 2. to meet the AC's of this card"
- Why is that? According to the github docs about default "health" files: "Default files will be used for any repository owned by the account that does not contain its own file of that type."

[the github docs about default "health" files] mentions what specific files are supported. The following are not included in that list, but you've included above as "will also be added as templates in .github":

.editorconfig
LICENSE (explicitly excluded in the linked documentation)

Did you mean something else by "template"? If so, please define that or point to the relevant documentation that defines it. And if you did mean something else - is there a compelling reason to not use the "health" file functionality for the files it does support? If you did mean something else by "template".... it's probably starting to build some scope creep. There's nothing in the acceptance criteria about files which aren't supported as "health" files except validating licenses.

emteknetnz commented 1 year ago

Re org level readme - yes sorry, we'd need to add useful stuff in there, presumably it's would be a composite of CONTRIBUTING.md and other meta files

That's really cool about the default health files I didn't realise that was a thing (didn't realise you had it linked in the description). That's a nice mechanism

Given that SECURITY.md is an official health file perhaps it does make sense to put the link to security@silverstripe.org in there with instructions

By "template" my (bad) assumption was that you could define "template" for these files .github that get copied to new repos, rather than ?symlinked? in if there isn't an existing file (presumably not copied). So given that, "templates" aren't a thing

We will need to scan all the modules for non BSD-3 licenses and it seems like the existing tool I linked to before would be useful for this. Given that tool was designed specifically to standardise specific files (including deleting files), the amount of scope creep added here is actually pretty low so I think it's worthwhile doing e.g. ensuring .editorconfig is standardised, deleting changelog.md, etc

GuySartorelli commented 1 year ago

Fair. Yup, sounds like that's a good plan of attack, then.

emteknetnz commented 1 year ago

I used github advanced search to look at all the repos with existing licences:

0bsd - 4 results https://github.com/search?q=user%3Asilverstripe+license%3A0bsd&type=Repositories&ref=advsearch&l=&l=

gatsby-source-silverstripe
gatsby-starter-silverstripe
nextjs-builder
nextjs-toolkit

bsd-2-clause - 2 results https://github.com/search?q=user%3Asilverstripe+license%3Absd-2-clause&type=Repositories&ref=advsearch&l=&l=

blog
graphql-devtools

bsd-3-clause - 134 results https://github.com/search?q=user%3Asilverstripe+license%3Absd-3-clause&type=Repositories&ref=advsearch&l=&l=

lots!

mit - 2 results https://github.com/search?q=user%3Asilverstripe+license%3Amit&type=Repositories&ref=advsearch&l=&l=

multi-domain
gridfieldqueuedexport

No other license types found

MIT is closest to BSD-2 https://opensource.stackexchange.com/a/582

BSD licenses - https://fossa.com/blog/open-source-software-licenses-101-bsd-3-clause-license/

BSD-3 - 3rd clause not in BSD-2 is (also known as the “non-endorsement clause”). This is the clause that prohibits users from using the name of the project to promote their derivative work(s)

BSD-0 is basically a 'do whatever you want license, including deleting the license'

Given that the non BSD-3 licenses are all more permissive, I see little reason to change them if we're not concerned about consistency.

Note developer-docs uses https://creativecommons.org/licenses/by/3.0/nz/ - this wasn't picked up by github advanced search - this type of license is very permissive like the other licenses we use

emteknetnz commented 1 year ago

@maxime-rainville I ran a quick and dirty script to find out what repos on silverstripe account (including unsupported) have no license

UPDATE: My original script was incomplete was didn't query every repo. I've updated the script, and gotten it to filter out any forks and archived repos - I'll do PR's for all the of the following to add BSD-3 LICENSE files

    [silverstripe/.github] => 1
    [silverstripe/api.silverstripe.org] => 1
    [silverstripe/demo.silverstripe.org] => 1
    [silverstripe/doc.silverstripe.org] => 1
    [silverstripe/forum.silverstripe.org] => 1
    [silverstripe/gatsby-poc] => 1
    [silverstripe/gha-auto-tag] => 1
    [silverstripe/gha-ci] => 1
    [silverstripe/gha-dispatch-ci] => 1
    [silverstripe/gha-generate-matrix] => 1
    [silverstripe/gha-issue] => 1
    [silverstripe/gha-keepalive] => 1
    [silverstripe/gha-pull-request] => 1
    [silverstripe/gha-run-tests] => 1
    [silverstripe/gha-tag-release] => 1
    [silverstripe/gha-update-js] => 1
    [silverstripe/github-issue-search-client] => 1
    [silverstripe/nextjs-poc] => 1
    [silverstripe/nextjs-poc-backend] => 1
    [silverstripe/one-ring-rentals] => 1
    [silverstripe/platform-status-page] => 1
    [silverstripe/silverstripe-checkboxgroupfield] => 1
    [silverstripe/silverstripe-config] => 1
    [silverstripe/silverstripe-dms-cart] => 1
    [silverstripe/silverstripe-elemental-layoutblock] => 1
    [silverstripe/silverstripe-frameworktest] => 1
    [silverstripe/silverstripe-gatsby] => 1
    [silverstripe/silverstripe-lessons-v4] => 1
    [silverstripe/silverstripe-multiuser-editing-alert] => 1
    [silverstripe/silverstripe-nextjs-starter] => 1
    [silverstripe/silverstripe-raygun] => 1
    [silverstripe/silverstripe-s3] => 1
    [silverstripe/silverstripe-tx-translator] => 1
    [silverstripe/silverstripe-upgrader] => 1
    [silverstripe/silverstripe-ux] => 1
    [silverstripe/sspak] => 1

Let me know if there are any where we do NOT want BSD-3 added to it

maxime-rainville commented 1 year ago

At first glance, I'm fine with BSD-3 on everything.

If the repo is a fork from something else, maybe validate what the original license was. The worst case scenario is if we forked something that was under something like GNU GPLv3 license, because we would be violating that license by republishing the thing under BSD-3.

If we are confident that a module was created by an employee of Silverstripe Ltd on Silverstripe Ltd time, I don't necessarily have beef with removing the name of the original author because Silverstripe would own the copyright anyway.

Also, I think it's legally allowed to publish a module under multiple licenses. For example, you could publish something under GPLv3 and if someone wants to be able to make changes without having to share them back, they can ask you for a commercial license (MySQL made a boat load of money that way back in the day). So changing the license after the fact, should be kosher in most cases as long as we own the original right on the thing.

emteknetnz commented 1 year ago

This a list of files with existing 'health files' - meaning a contributing, support, security or code-of-conduct style file - again used a script

Before deleting things, we need to merge the .github PR and try deleting files in a single repo to validate that the .github health files are "passed through"

    [silverstripe/comment-notifications] => 1
    [silverstripe/cwp-agencyextensions] => 1
    [silverstripe/doorman] => 1
    [silverstripe/fluent-regional] => 1
    [silverstripe/multi-domain] => 1
    [silverstripe/silverstripe-asset-admin] => 1
    [silverstripe/silverstripe-assets] => 1
    [silverstripe/silverstripe-auditor] => 1
    [silverstripe/silverstripe-blog] => 1
    [silverstripe/silverstripe-cms] => 1
    [silverstripe/silverstripe-cms-events] => 1
    [silverstripe/silverstripe-colorpicker] => 1
    [silverstripe/silverstripe-comments] => 1
    [silverstripe/silverstripe-content-notifier] => 1
    [silverstripe/silverstripe-contentreview] => 1
    [silverstripe/silverstripe-crazy-egg] => 1
    [silverstripe/silverstripe-crontask] => 1
    [silverstripe/silverstripe-dms] => 1
    [silverstripe/silverstripe-documentconverter] => 1
    [silverstripe/silverstripe-dynamodb] => 1
    [silverstripe/silverstripe-elemental] => 1
    [silverstripe/silverstripe-elemental-bannerblock] => 1
    [silverstripe/silverstripe-elemental-fileblock] => 1
    [silverstripe/silverstripe-environmentcheck] => 1
    [silverstripe/silverstripe-event-dispatcher] => 1
    [silverstripe/silverstripe-faq] => 1
    [silverstripe/silverstripe-fontpicker] => 1
    [silverstripe/silverstripe-framework] => 1
    [silverstripe/silverstripe-frameworktest] => 1
    [silverstripe/silverstripe-fulltextsearch] => 1
    [silverstripe/silverstripe-globaltoolbar] => 1
    [silverstripe/silverstripe-gridfieldqueuedexport] => 1
    [silverstripe/silverstripe-html5] => 1
    [silverstripe/silverstripe-hybridsessions] => 1
    [silverstripe/silverstripe-iframe] => 1
    [silverstripe/silverstripe-installer] => 1
    [silverstripe/silverstripe-installer-wizard] => 1
    [silverstripe/silverstripe-ldap] => 1
    [silverstripe/silverstripe-linkfield] => 1
    [silverstripe/silverstripe-mathspamprotection] => 1
    [silverstripe/silverstripe-mfa] => 1
    [silverstripe/silverstripe-mimevalidator] => 1
    [silverstripe/silverstripe-module] => 1
    [silverstripe/silverstripe-mssql] => 1
    [silverstripe/silverstripe-multiform] => 1
    [silverstripe/silverstripe-omnipay] => 1
    [silverstripe/silverstripe-postgresql] => 1
    [silverstripe/silverstripe-raygun] => 1
    [silverstripe/silverstripe-realme] => 1
    [silverstripe/silverstripe-redirectedurls] => 1
    [silverstripe/silverstripe-registry] => 1
    [silverstripe/silverstripe-reports] => 1
    [silverstripe/silverstripe-restfulserver] => 1
    [silverstripe/silverstripe-routewhitelist] => 1
    [silverstripe/silverstripe-saml] => 1
    [silverstripe/silverstripe-search-service] => 1
    [silverstripe/silverstripe-secureassets] => 1
    [silverstripe/silverstripe-securityreport] => 1
    [silverstripe/silverstripe-segment-field] => 1
    [silverstripe/silverstripe-selectupload] => 1
    [silverstripe/silverstripe-serve] => 1
    [silverstripe/silverstripe-session-manager] => 1
    [silverstripe/silverstripe-sharedraftcontent] => 1
    [silverstripe/silverstripe-simple] => 1
    [silverstripe/silverstripe-siteconfig] => 1
    [silverstripe/silverstripe-sitewidecontent-report] => 1
    [silverstripe/silverstripe-smime] => 1
    [silverstripe/silverstripe-spamprotection] => 1
    [silverstripe/silverstripe-staticpublisher] => 1
    [silverstripe/silverstripe-staticpublishqueue] => 1
    [silverstripe/silverstripe-subsites] => 1
    [silverstripe/silverstripe-superglue] => 1
    [silverstripe/silverstripe-tagfield] => 1
    [silverstripe/silverstripe-taxonomy] => 1
    [silverstripe/silverstripe-testsession] => 1
    [silverstripe/silverstripe-textextraction] => 1
    [silverstripe/silverstripe-theme-colorpicker] => 1
    [silverstripe/silverstripe-theme-fontpicker] => 1
    [silverstripe/silverstripe-totp-authenticator] => 1
    [silverstripe/silverstripe-userforms] => 1
    [silverstripe/silverstripe-versioned] => 1
    [silverstripe/silverstripe-versioned-admin] => 1
    [silverstripe/silverstripe-versioned-snapshot-admin] => 1
    [silverstripe/silverstripe-versioned-snapshots] => 1
    [silverstripe/silverstripe-versionfeed] => 1
    [silverstripe/silverstripe-webauthn-authenticator] => 1
    [silverstripe/silverstripe-widgets] => 1

GuySartorelli commented 1 year ago

The following don't have creative-commoners forks, though don't really seem appropriate to even have LICENSE files in them

You can just create a fork - forks are free. What about them makes them seem like having a license isn't appropriate? I don't feel strongly either way, so feel free to just leave your opinion and not add licenses if that's what you choose. It just feels a little arbitrary right now given some of the repos (some very long abandoned) that did get licenses added.

GuySartorelli commented 1 year ago

PRs merged. Reassigning to @emteknetnz for next steps (and to respond to the above comment)

emteknetnz commented 1 year ago

Looks like we totally misunderstood what the health files actually do

This do not "pass through" to individual repos - instead what they do is show up as links when you open a new issue or pull request, e.g.

emteknetnz commented 1 year ago

I've spun off the 'update all the files' into a new issue - https://github.com/silverstripe/.github/issues/70 as it's greatly increased the scope of the original intention of this issue

I'll close this issue

silverstripe / .github