New Guide for software development environment

[johnscancella]

Most (if not all) your guides focus on the processes or best practices assuming you have a good development environment. having a good development environment is sometimes taken for granted until you no longer have a working environment. Perhaps you consider creating a guide/best practices on what that good development environment might look like?

Things that it might detail or include:

• What the support contract between developer and sys admin
  • Like reliability
  • VMs can't just be shutdown or locked out without notifying the developers
  • Filesystems are robust and don't require developers to test to make sure they are working properly
  • etc
• Self provisioning of resources by developers (restricted by some sort of quota, so as not to consume all resources)
• What kind of access a developer has on each environment
  • full unrestricted admin(sudo) on development environment
  • "regular" user permission on production
• Issues certificates so that dev and test environments can have TLS on during development
• Repeatability (automation)
• If in house can not provide these services, procuring outside services

Basically if you had to go to a high level manager and justify why a developer needs these things so that they can do stuff like continuous integration, or agile, how would you pitch it?

[mbland]

I like this idea. Done: https://github.com/18F/dev-environment

Just an empty skeleton right now, of course, and https://pages.18f.gov/dev-environment/ won't show up until we push a new commit. If you'd like to fork it and send pull requests with some initial ideas, feel free. I think @monfresh in particular might be interested in pitching in.

One thing to bear in mind: As government employees we have to be very careful not to endorse particular commercial products. We can talk about Open Source all we want, however.

[johnscancella]

Awesome! Thanks for getting it started. I will definitely be making some pull requests when I find the time to work on this!

[acdha]

:+1:

In addition to the legal requirement to avoid endorsing specific products, I also think a guide like this benefits from focusing on the benefits – e.g. the important part is that as a developer I have an API to spin up a VM from a known starting point, not which hypervisor or whose server it runs on – and that conveniently saves the hassle of trying to enumerate a constantly-changing list.

[inadarei]

my 2c:

this is what Docker exists for, to make creation and deployment of reliable environments easy without pages and pages of documentation explaining the "hows" and then hours spent when the aforementioned documentations inevitably miss subtleties of our snowflake environments.

In the spirit of "code rules over written instructions, since latter is doomed to get outdated" maybe the goal here is to create Docker-based provisioning automation, instead.

I'd be willing to help, if there's interest.

[johnscancella]

@inadarei I would agree, however our organization is unable to use docker. This was an attempt to put the core concepts of what a docker build gives you into a document so you can hand it to a general manager.

[acdha]

@inadarei True but Docker is only part of the answer – you still need to manage the Docker hosts and have higher-level organization across hosts (service discovery, fail-over, scaling, etc.). I do think that's a good reminder, however, that when in doubt this should be a short, generic summary of the desired goal (e.g. repeatable builds, isolation, etc.) and a note that this is satisfied by various projects like Docker.

[inadarei]

@acdha, that is true for production systems, but for setting up a dev environment you typically don't need much of "service discovery, fail-over, scaling, etc.". And when you do: there are things like Ansible.

But you are right: the main point here is to minimize written prose and maximize automation, because larger the "documentation" quicker it gets hopelessly outdated. And it can never cover all the edge cases to be truly useful for everybody.

cheers.

[acdha]

@inadarei my thinking was that if e.g. you're using a service discovery system in production you need some way to test the same mechanism in development but, yes, this is definitely heading into a place where needs diverge widely.

I think your main point about automation should be very prominently mentioned at the top – don't trust anything you don't verify regularly, etc. That's a more important lesson than any one particular tool.

[inadarei]

Ha, yeah. When and if things get so complicated that you need service discovery etc. imagine documenting something like this: https://github.com/apiacademy/ansible-consul-demo in prose and explaining hundreds of steps that would need to be manually executed :)

[inadarei]

"don't trust anything you don't verify regularly" +1000 :+1: