Tell users about the community-developed resources that exist

timpaul commented 4 years ago

What

An increasing number of people have created resources based on our work. For example ports of GOV.UK Frontend, Sketch templates, code snippets and helpers, or entire design systems.

We maintain a list of these but we've never made it public, because we can't vouch for the quality of the resources. there's also a public list here but it's not maintained by the team.

Why

If we published the list it could:

help people find these often useful resources
stop people unnecessarily making their own versions
help people understand that we don't own them

Done when

[x] We've checked known resources and looked for more
[x] We've done some user research #1256
[x] Analysis of research findings and ideation #1257
[x] Publish a list of known community resources #1282

Related issues

Document that govuk-react is not a project maintained by our team

m-green commented 4 years ago

Once this is published, I should add a link to it in the new migration docs.

36degrees commented 4 years ago

Off the back of a conversation with @timpaul the other day, I spent some time thinking about the sorts of criteria we might look for before we link to a resource:

Community resources

If you want add a new resource to the list, you must:

publish it on GitHub under a recognised government GitHub organisation

have a documented process for users to get support

have a documented process for contribution[, including a code of conduct?]

use the same HTML markup as GOV.UK Frontend, for resources that use HTML

have sponsorship for the project from [???]

We will review the list of resources periodically, removing any resources that:

have open issues asking about support for the project that have been open for more than one month

are more than 3 months behind GOV.UK Frontend

have had no activity for x months

If you are no longer able to support a resource, make this clear by updating the README and archiving the repository. Where possible, give users as much notice as possible and try to find a new owner for the project.

These are just initial thoughts, and I'm not even sure it needs to be this hard-line – we shouldn't rule out e.g. still listing 'everything' but with a clear indication of support level, or split into sections with explanations.

andymantell commented 4 years ago

What would be really helpful from my perspective would be to have something like an alphagov-community GitHub organisation where repositories could live for things like community ports. I guess not mandatory, but in the absence of anywhere better to put them they could live here. For example, I maintain https://github.com/surevine/govuk-react-jsx which is currently under Surevine's GitHub account. I also have plans to release a Python/Jinja2 port of the govuk-frontend macros, probably done out of hours and on my personal GitHub account. In my mind it would have the following benefits if I could host it within alphagov-community:

Increased discoverability - apart from using Google, people aren't going to find things on my GitHub profile
Some sense of reassurance for consumers - if GDS were to spend an hour or two casting an eye over a project when it first arrives in the "community organisation" it would give people some assurance that the project was fit for purpose
If a project became unmaintained, it would easily allow GDS to reassign maintenance since you would have at least some form of ownership of all the repositories. This would give consumers a bit more long term assurance.
It makes it easier for people like myself to maintain libraries as they move between organisations, in and out of the civil service.
Projects are more likely to garner contributions from others - more likely than something hosted on my own account.

I have arrived at this thread after having been asked for my response to some of the above issues with regards to govuk-react-jsx - the person in question was nervous of using my library since it was relatively new and reliant at the moment on just myself for maintenance. If it were housed in a community organisation with a light touch approval process this would give them some confidence.

I can see that it might have some issues as you've raised above - particularly around endorsement of the quality of projects, or perceived endorsement of the underlying framework such as React. I feel like some guidance on the nature of GDS' involvement in the repositories would be enough to clear this up however. Perhaps all the projects would have a prominent section at the top of their readme files stating this.

I realise all of this might be beyond what you were planning, but just wanted to float the idea. Even just the list of resources you mention would be a great start - and a clear process and set of requirements for getting onto the list (And staying there).

36degrees commented 4 years ago

Thanks @andymantell – this is really helpful. We'll take it into consideration when we start looking at this properly.

frankieroberto commented 4 years ago

@andymantell @36degrees I also think that moving some of these shared resources into a single GitHub organisation account would be helpful. @natcarey and I created https://github.com/x-govuk as a potential option for this, although we've not started actively using it yet.

It could equally just be in alphagov, although that's already a fairly confusing org name... 😉

I'd also suggest having a naming convention for ports of the nunjucks macros to other frameworks, eg govuk-frontend-[framework-name], to make them a bit easier to find (otherwise we'll have govuk-design-system-rails and govuk-react-js and jinja-govuk-frontend and so on).

andymantell commented 4 years ago

The naming convention sounds good but bear in mind certain combinations may be already taken on package repositories. Although npm for example does allow scopes so the package name on the repository could be @x-gov/govuk-frontend-react rather than just govuk-frontend-react. In my case, govuk-react-jsx was chosen because all other sensible package names were taken.

frankieroberto commented 4 years ago

@andymantell that is a good point. Although perhaps it's worth getting in touch with the author of govuk-frontend-react and asking if you can collaborate & adopt the package name? (That one looks like it's an experiment on version 0.0.12)

For what it's worth, the Rails port that I've contributed to is currently called govuk-design-system-rails which I think is because at some point we got confused between the GOV.UK Design System" and "govuk-frontend", as the two are so closely related. I'd be willing to rename it though if we could settle on a convention.

nataliecarey commented 4 years ago

At HMRC we've got play-frontend-govuk https://github.com/hmrc/play-frontend-govuk

We use twirl templates in play which we run in scala. The branding of our new round of updates is play-frontend and we built an exact port of govuk-frontend as well as a separate port of hmrc-frontend so the projects are play-frontend-govuk and play-frontend-hmrc

Our goal has been to keep the govuk port unopinionated and not department specific, therefore we would hope it can be contributed as a library for anyone using twirl/play/scala.

I'd have no problem suggesting we move/fork that library to x-govuk/govuk-frontend-twirl (or maybe it should be x-govuk/govuk-frontend-play)

alphagov / govuk-design-system