defra / dst-guides

Guides relating to the work of the Environment Agency's Digital Service teams

Digital Service Team Guides

WE ARE MOVING

These guides started out as being something to support a single Digital service team, but then evolved into being a community hub to capture useful info for all digital service teams.

We now have an official home for all development in Defra, not just digital teams at Software development standards (SDS).

As such much of the content here will be migrated to the new project. Eventually DST-Guides will close.

In the interim we ask all new developers; permanent or contractor to check out both repos before they start working. If anything is duplicated or inconsistent between the two, SDS takes precedence.

Introduction

These guides relate to the work of Digital Service Teams (DST) in the Environment Agency who are building new Digital by default services.

Guides

• Applications
  • Error Notifications
  • Software Libraries
  • Continuous Integration for Ruby based projects
  • Working with engines in Ruby on Rails
• GitHub
  • New projects
• Process
  • Releases
  • Accessibility
• Services
  • Apply for a standard rules waste permit
  • Submit your flood or coastal erosion risk management project proposal
• Style
  • JavaScript
  • Markdown

About

They cover processes, decisions, how-to's and notes. They are intended to help with onboarding new team members, provide details for contributors, and are part of our efforts to keep our work consistent across the services and projects we build and maintain.

It has been produced as a series of markdown files to make the process of adding and maintaining the documentation as simple as possible. Nothing is fixed and anything documented here is open to change.

It is maintained under source control to cater for this, allowing anyone to make suggestions for improvement via the standard pull request process.

It is pushed to GitHub to make it publicly accessible and to render the content in a presentable format.

It is heavily inspired by the work of ThoughtBot.

Contributing to this project

Please read the contribution guidelines before submitting a pull request.

License

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the license

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.

dst-guides's Issues

Need guidance on publishing to public registries

We've done a bit of this with the NPM and RubyGems registries, but it would be good to capture the guidance on when and how we should do it.

Consider renaming this repo to reflect its true scope

This repo was originally created by one of the pioneering teams in the Environment Agency, and its current name reflects this. However its scope, and the people using / contributing to it, has since increased. An updated name may be appropriate.

We should decide its new scope, in particular whether it encompasses all Defra or remains at the Environment Agency level, and propose new names as appropriate.

Pages under /services/ still contain links to /EnvironmentAgency/ organisation

The pages describing the Waste Exemptions and Flood Risk Activities Exemptions services contain links to the repos for those services and these links have /EnvironmentAgency hard-coded into them.

These should be updated to /DEFRA following the renaming of the organisation.

Missing Fish, Flood and PAFS

There is currently no information in here on the fishing licensing service, flood services or PAFS.

It would be good to have this (overview) information all in one place, especially for people who are new to the services.

Missing guide link in WEX README

A link to the Solution release process is missing from WEX readme.

Error in work flows

Found an error in the Workflows guide specifically https://github.com/EnvironmentAgency/dst-guides/blame/master/process/workflows/README.md#L46

It states

and once complete merge it back into Develop

It should be

and once complete merge it back into Master

Workflow guide is still quite Ruby/team specific

The content for Workflows still talks in terms of a Rails/Ruby based project and in terms of the old Digital Service Team. The workflows are still applicable and I would advocate that others use them for similiar project types in their chosen tech stack, but first we need to make the guide more generic.

Make merge to master clearer in release of top level projects for WEX

The current solution release process does specify the command to use when generating a new release git merge develop however some users (namely me!) might be tempted to use git merge --no-ff develop assuming its just a typo.

It needs to include some text covering why not to do this, specifically it creates an extra commit which is not on develop, which means they are not exactly in sync when they should be. This makes tracking the history and ensuring the branches are the same easier.