eregs / eregs.github.io Goto Github PK

A logical progression of #54 and #55 is to include a transpiler for our JS code. I think this would make the code base easier to grok by more developers and simplify a lot of our code.

Love that this exists, but just wanted to point out that a very-similarly named government tool already exists: https://ereg.elections.ca/

Is this a concern? Will one of the projects be changing its name?

While setting up a copy of this site I ran into two questions that would be nice to answer in the readme:

After I ran “bundle install”, the result ended with this message:

Post-install message from html-pipeline:
-------------------------------------------------
Thank you for installing html-pipeline!
You must bundle Filter gem dependencies.
See html-pipeline README.md for more details.
https://github.com/jch/html-pipeline#dependencies

Does this project expect the reader to ignore that message, or does it expect the reader to do something at that point?

After I ran the Jekyll command, the OS X firewall system popped up a dialog box that says “Do you want the application ‘ruby’ to accept incoming network connections? (Deny / Allow)”. What does this project expect the reader to choose?

We have a tendency to cut releases of our libraries when they are convenient for downstream projects. This works pretty well and should probably continue, but doesn't help downstream projects that we're unaware of. I propose that we aim to cut new releases at least once a quarter (unless no changes have been made in that time).

What do you think?

Since our workshop, I've had a lot of thoughts bouncing around in my brain wrt what eRegs needs to be in order to catch up to the demands being placed on it now and in the future. I want to continue conversations we started during the workshop around the technical direction of eRegs.

Goals:

• new back end developers, who are likely inexperienced in the exact pieces that comprise the parser, can reasonably quickly get up to speed on core parser concepts, its interface(s) and the pertinent information around the regulations ecosystem that will make clearer why the parser does things that it does.
• all new developers can understand how the different pieces of eRegs fit together - how -site and the back ends work as well as the ability to find out where all related data comes from (GPO, Federal Register, etc) and how it relates to the parsed content.
• front end developers can understand how to create a theme or otherwise extend the UI of eRegs
• ?

Why?

• hopefully, longer term, this work will help enable us to move both 18F and CFPB to shared core instances of eRegs
• on the 18F side, it should speed up development of new client instances
• more people involved increases the reach, potential and capacity of eRegs
• more brains = more ideas
• can get more meaningful open source contributions
• ?

How?

• thorough, well-designed and organized documentation
• implementing some kind of theme/skin system
• thinking about the parser interfaces as public ones, documenting and potentially restructuring code to bring to the surface clear touch points into the process
• ?

Any revisions/thoughts/additions?

We could rename this repo so that the repo is eregs.github.io rather than eregs.github.io/eRegulations. Any objections?

18f's regulations-parser, -core, and -site are intended for general agency usage. I recommend we move them into the eregs github organization to limit confusion from new users and share governance.

ATF uses https://regulations.atf.gov now.

We've created many, many presentations around eRegs, but they are all locked up in Google Drive, etc. Let's export them and post them somewhere on eregs.github.io

Maybe include a viewer like http://viewerjs.org/ ?

Airbnb's linter configuration has become a decent standard; let's adopt it rather than rolling out own. I propose we include eslint-config-airbnb and replace our existing eslint with

extends: airbnb

This will no doubt raise lots of issues; we can go through them and turn off all of those rules to a "quiet" state and then begin fixing.

https://github.com/cfpb/regulations-bootstrap

I was just checking in and saw there's a new page for N&C - https://eregs.github.io/features/notice-and-comment/ - yay! I'd suggest promoting it to a left sidebar item so that people will see it, since it's cool and important. :)

We've been sort of shoving everything in the left-hand navigation rather than thinking about the site's structure. Currently, we have:

• Overview and live instances (which is basically just a link farm to other pages)
• Features
• Code and documentation
• Theming an instance
• History, present, and future
• Introduction to regulations
• Guidelines (how to write regulations)
• Contact and Governance

I propose the following instead:

• Overview (ideally revamped content to be more of a summary)
• History and Trajectory (includes scope section from current history page)
  • Projects and Phases (see #61, includes parts of the "Features" content)
  • In the News (current, on the History page)
  • Presentations (split this from the news part)
• Guides
  • Introduction to regulations
  • Creating an eRegs instance (revised content, collected from ATF docs, /story, Theming an instance, etc.)
  • Architecture (revised content, collected from /technology, read-the-docs, etc.)
  • Writing regulations guide
• Contact and Governance (now to include open source info)

https://github.com/cfpb/fr-notices

Mentioned this in Slack, but noting it here too to track this issue - recent updates to gh-pages in this repository (such as adding this diagram and this page) aren't showing up on https://eregs.github.io/ - and I'm not sure why not.

GitHub now lets you enforce HTTPS for *.github.io domains:

https://github.com/blog/2186-https-for-github-pages

The site already works over HTTPS without errors: https://eregs.github.io So this should be a trivial fix.

As we've added new features (particularly Notice & Comment) which have required significant JS code, we've run into difficulties testing the frontend and following the logic between events. React should help the testing problem by providing very clean abstractions. Redux should make the eventing system easier to follow as it keeps track of the app's state in a single location.

We've also spoke a bit about isomorphic JS and how that could solve some of our split-brain backend-frontend issues. Getting these libraries in will make that direction easier to take, but let's keep the existing backend-generated HTML and focus only on the chunks of markup that are generated in JS. We can revisit once we prove the strategy's usefulness.

The incremental replacement approach is being using now in https://github.com/18F/calc and described in this talk: https://www.youtube.com/watch?v=BF58ZJ1ZQxY

Thanks to @jmcarp for suggesting this originally. What are your thoughts, @theresaanna @ascott1 @xtine?

Similar to #31

We should link to the research docs that are now living in the respective wikis. The eregs-platform wiki has the links out to all instances with research docs: https://github.com/18F/eregs-platform/wiki

Currently, regulations-site is a CFPB branded Django app. It's the result of a process where we were rapidly testing ideas and re-designing on the fly. This means that there are shards of code left where they shouldn't be and overall the app feels a bit messy.

As 18F expands regulations-site there is a need for it to be re-branded for various agencies. The current solution for this is to fork a version of reg-site. This works ok, but means that it's hard to contribute back to the original project.

Proposal

github.com/eregs/regulations-site could house a new and stripped down version of regulation site. This would contain minimal templates, styles, and JavaScript to produce a working regulations-site when paired with regulations-core. The output would look something like a wireframe.

Based on this frame of a site, individual organizations would be able to create themes that would contain template, style, and JS overrides (or complete replacements). This would allow organizations to style their own versions of eRegs however they'd like while also being able to use the base site.

Open questions

• Is Django the right format for this? Could it be a static site generator? Something else?
• Once of the nice things about the current setup is that eRegs is both a single page application as well as a Django app that works without JavaScript. Is this something we would like to preserve? If so, how else might we best accomplish this?

From @brittag:

What about documenting how people can become part of the eregs org?
I’d also be interested in seeing a list there of the orgs/teams that are currently actively involved with eregs (even if it’s just CFPB and 18F)
And where should policy changes be discussed? Do people just discuss them by making an issue or PR on the docs repo? Would be good to note that
you likely already saw this, but Compliance Masonry has been talking about governance, and there’s a good list of questions in this repo from folks: opencontrol/discuss#5
And we’re looking at openopps/openopps-platform#1287 + https://github.com/openopps/openopps-platform/blob/dev/GOVERNANCE.md as a model

Add mention and documentation for regulations-stub.

Currently https://eregs.github.io/technology/ explains where to find the various parts of eRegulations and what they do. We have a bunch of other documentation that's a little bit hard to find from that page - you have to poke around a bit to find it. For example: some of the repository readmes have extensive explanations in themselves, and some of the readmes also lead to additional resources.

For example:

• https://github.com/18F/regulations-parser links to https://regulation-parser.readthedocs.org/en/latest/
• https://github.com/18F/regulations-core links to http://regulations-core.readthedocs.org/en/latest/
• https://github.com/18F/regulations-site links to https://github.com/18F/regulations-site/blob/master/README_BACKBONE.md

Let's make this /technology/ page better communicate where to find explanations.