brigadehub / brigadehub Goto Github PK

In reference to #10 #12 #15 #11

We want to make sure every pull request has tests run on it, and that it's solid before we merge.

• MongoDB installation instructions: After setting it up through HomeBrew, the /db/data directory needs to be owned by a non-root owner.
• nvm installation stuff
• bash stuff

Need a list of what every new member that comes to hack night needs to have done. For example:

• Sign into slack
• Sign up for newsletter
• Github permissions
• Checking In

Anything that can be automated, should be when they sign in with Github.

We need a landing page for the projects as a whole, and for each project individually.

Projects should be able to add arbitrary markdown content to their own page.

Design should follow http://kodujdlapolski.pl/en/projekty/ and http://kodujdlapolski.pl/en/projects/easy-rider/ respectively

Collect and publish findings from user research. Talk to as many brigades as possible to understand what they use now, what their pain points are regarding their site, what do they love, what would it take for them to change?

As the MVP for BrigadeHub will most likely just cover project display and marketing, the previous issue of conflicting overlap should be more or less mitigated for now. I do believe, though, that we could both benefit from import/export to/from CivicMakers for project data as both tools mature. This is open for that continued discussion :)

cc/ @sfbrigade/project-civicmakers @grodeska

Some possibilities:

• having a button in the BH project management page to publish project to CivicMakers
  • what that would need on the CivicMakers side is the ability to populate your add/project page via URL parameters, I can help with that if needed.
• down the line, an API integration with seamless data pulling would be spectacular.

CivicMakers has been developing a platform for civic collaborations as part of Code for San Francisco since last March. We are about to launch our beta which you can see here:
https://civicmakers.firebaseapp.com/project/-K58FF9D5ILUb7givIwH

Trent and Lawrence have begun talking about the significant overlap between the project focus of Brigadehub and CivicMakers. We're opening this issue to talk through this overlap and outline a path forward for integration and collaboration.

Current proposal is to share problem statements and assumptions for the project pages of CM & BH and move forward from there.

cc @therebelrobot @afomi @ybentz @sfbrigade/project-brigadehub @LarryBafundo

@jszwedko showed this to me today, and it hits a lot of the core features we need for the content management portions of this application: markdown based content updating, coupled with github for updating files, which would allow us to access the posts themselves via the API. I'd want to take a look at how permissioning could be locked down.

It's possible that we'd need to fork prose, and make it more suitable for our needs (specifically permissioning portions of a content tree). Definitely the direction we want to take a look at though.

We have a lot. and they're kind of all over the place, color-wise. I'd like to have similar concepts to have a similar color for scanning through issues, but if anyone has UX/design experience and can see what looks alright in the Issues section, please take a crack at it.

It would be great if brigades weren't tied down to a specific source control management solution with BrigadeHub. If a brigade wants to use hosted GitLab or any other 'bring your own scm' solution in contrast to GitHub then they should feel free to do so.

To that effect, I want to write an abstraction layer for our interactions with an scm platform.

Example: Associating a group or repository with a project requires contacting an scm platform endpoint; collecting repositories, groups, and their respective metadata; then creating the model associations between data sets (project -> group).

I'll aggregate the related calls to GitLab/GitHub/Etc in one library to expose to my fellow contributors as a single point of entry for scm related actions.

Potential scms:

• GitHub (lol)
• GitLab hosted
• GitLab deployed
• Phrabricator

I won't target Phrabricator due to MVP but it should be kept in mind as a potential target. I really don't see it being picked up by a brigade, however.

@therebelrobot Let me know what kind of interaction with GitHub is planned/needed so I can limit scope.

Initial feature set:

• Authorization
• Repositories
• Users
• Issues
• Organizations

Anything outside of this feature set should be specified within a separate ticket.

ToDo:

• Internal API and usage documentation for wrapper library (stored in wiki)
• Test layout and code structure
• Possibly create a 'fake' GitLab instance for testing
• Enough of a code structure to make API calls
• Tests with cached responses from scm
• Actual code: Auth
• Actual code: Repos
• Actual code: Users
• Actual code: Issues
• Actual code: Orgs

Resources:

• https://www.npmjs.com/package/github
• https://www.npmjs.com/package/node-gitlab
• https://www.npmjs.com/package/sepia

Markdown, stored in mongodb, pulled and rendered on server request.

We need a way of rendering, editing, previewing the markdown.

Need to make a new theme in the themes/ folder that's a pretty close clone of the current code for poland website

Currently residing in /themes/atl, and is a clone of the codeforatlanta website

dependant on #3

I saw in the goals that we're interested in not tying brigade activity to solely one platform, which previously aired in favor of GitHub. It got me thinking that BrigadeHub, down the road, might benefit from some sort of ifttt.com-type setup.

If this is of interest, there is a FOSS platform called Huginn that might be of interest.
http://blog.pragmasphere.com/2014/06/10/huginn-the-opensource-iftttyahoo-pipes-mix/

The main issue is that driving Huginn only via API (which is probably what this would need), is not yet implemented:
huginn/huginn#176

Having said that, the main developer is welcoming of the idea, and seemed to indicate that it shouldn't be too difficult.

Anyhow, again, the aim of this would be to have a backend service (Huginn) for BrigadeHub that our platform could talk to via API to create "agents" (in Huginn-speak) for all the connections between external services and BH. There are already a bunch of agents available, and they're designed to be pretty easy to write, so it should be accessible to folks who want to add new ones to BrigadeHub. We'd need to create, at minimum, a new agent that knew how to poke BH and create new "items". In Huginn, agents send to agents, until one acts outside Huginn. Our BH agent would be that agent that sent messages to us based on other agents checking other services.

Anyhow, this is very much down the road, but thought it might be an interesting approach instead of building our own event listener system :)

This section of the README is now obsolete. Needs to be updated to reflect new file/folder structure.

So for CodeAcross, we're going to have 5 hours of actual hack time, with other events occurring in between, I wanted to make sure we're using the time as effectively as possible.

Before starting

• Have the application running locally on your machine
• Have Zenhub installed in your chrome browser so you can see the boards we are organizing
• Have looked through and understand the Brigadehub Roadmap (#45) and the Alpha release feature list (#51)

When you are ready to start

• Pick from the github issues tagged with ALPHA, and in the Alpha Zenhub column you feel you can make progress on
• If you are working on a feature that is not currently listed in the GH issues list, make sure it falls within the alpha list at #51, and check with @therebelrobot to see if it's already there, if not, open an issue for it before beginning work.
• When you begin working on a feature, assign the issue to yourself so others know you are owning it.
• Any features you want to work on should be done in a feature/<feature-name> branch, branched from the edge branch
• when ready to merge in, a PR should be opened from that branch into edge
• You should be regularly git merge edgeing while you're working, so you have an up-to-date version you're working on.
• Any merge conflicts are primarily the responsibility of the PR opener to resolve.
• We should be focusing on small 1 hour sprints for merging, so focus your work on what you can accomplish in the next hour. We should be checking in our code after every hour, even if incomplete. I (@therebelrobot) will be managing reviewing / merging the PRs, and will be updating edge with the new code as the day goes on.

When you are finished

• open a final PR to edge, indicating that it delivers the individual issue you have been working on
• let @therebelrobot know to review it, or tag him in the PR
• grab a drink of water, take a small break, and jump back in the issue list

If you have any questions or concerns about this attack plan, please let me know, and one of us can help. I'll be adding more to this list before tomorrow, so keep an eye on it.

The brigade should be able to list redirects they want to/from in the admin panel, to maintain links, etc.

So my initial thoughts for branching were:

• edge - current nightlies, possibly unstable
• release/v<x.x.x> - stable releases, where <x.x.x> is the semantic version, should also be tagged and released in Github
• feature/<feature-name> - upcoming features, with a descriptive title
• demo - the version that's running on Heroku, with whatever additional configurations needed for that.

These are just initial thoughts, and absolutely up for discussion, I just wanted to get some kind of structure in here.

Nightwatch - Should be specific to themes

We need a landing page which shows the following:

• Name and basic info about the brigade
• Brigade logo/images
• Way to join Slack channel
• Next Meetup event
• A small form to sign up for newsletter (should tie into user model, with a non-logged in fallback)
• A sampling of the projects
• A sampling of the blog posts
• Partner information
• A way to update this information via an edit page

Design should be based off Code for Poland

We need a working About page with the following features:

• Info about the leadership team (should default to user model data)
• Contact info for leadership and brigade as a whole
• A contact form to send an email to a generic contact email for the brigade
• a way to update this info via an edit page
• Styling [https://github.com//issues/139]

Design should be based off http://kodujdlapolski.pl/en/contact/

Notes from 2/17/16:

https://docs.google.com/document/d/1jGrBHXza8AljBiI-P7f1BWa7tPFFkTb1Qmh1lC8JwvU/edit?usp=sharing

Problem

• Target audience: 95% of brigades that don’t want to deal with their site.
• A Brigade website is a completely different animal
  • Align tech with organization goals
    • separate data layer
    • presentation layer would be minimal
      • could be customized - themes
    • Meetup, EventBrite is more current
  • Chicago’s website as a successful example (presentation layer)
  • Atlanta is good, too
• Setting up online infrastructure for a brigade is a PIA
  • Requires resources that could be better spent on projects that directly impact the city.
• Maintenance / content should not be limited technologically to only a few people
• Supports “Brigade in a Box”
• BrigadeHub as source of truth for Brigade. Other sites pull

History of current website - picking Jason’s brain

• Original solved problem of “Need a damn website”
  • was a single page landing site
• Hannah was leading the brigade network and made a site a priority
• Need for infrastructure
• combined elements form a number of other c4a sites
  • project list
  • blog
  • about, other stuff added over time.
• jekyll static site generator
  • prose for editing
    • almost ok enough for normal people.
  • markdown, github
  • why jekyll
    • hosted on github
      • free
      • no sys-admin needed, 100% uptime.
    • looked at Laddr (cms? code for philly)
      • requires odd and difficult installation (LINUX vm)
      • maintained by a single individual - high risk
• projects getting marked as inactive (getting removed), erroneously
  • controlled via google spreadsheet, very fragile, prone to error
• allow people to see projects that are sorted by technologies, etc.

Existing Options - pros and cons

Wordpress / Drupal

• Very Heavy, lot of overhead code. Steep learning curve.
• Plugins allow rapid delivery, but unstable product.
• Requires ongoing developer commitment

Commercial Products (Squarespace)

• Extremely stable, very robust - dedicated development, service, support team.
• Not hackable at all
• Pricey

Desired features

• scripts to install/deploy
• GUI-driven
• Heroku pipeline
• minimally customizable by Brigades
• Ease the pain of transitioning new members to active members
  • coordinate with Member Support
  • help returning members engage with projects
  • increase conversion rate of red nametags to blue
  • member profile - skills, interests, availability, help. OAuth: cross-platform integration: git, Slack, FB?
  • project resources: free service subscriptions
• BrigadeHub as source of truth for Brigade.
• Evergreen updates

Launch stages

Prototype at alpha.codeforsanfrancisco.org (see Andrew Hyder for DNS)

pre-MVP = alpha - make it work for us

MVP = beta - get it in the hands of other brigades

Why BrigadeHub vs wordpress

Security (authentication via wordpress or oAuth)

Themes vs. Skins?

Reasonable defaults

Squarespace - themes made by central group

Keystone CMS - node based, how they’re handling themes.

As stated by @jnaulty on slack:

Hey, we've had a couple people ask us for the purpose of brigadehub and the niche it's supposed to fill, maybe we could have a mission statement or list of objectives or something that could satisfy these people's curiosity.

So I have a brief listing of the goals in the main README, which lists the following goals for the project. This is definitely up for discussion/tweaking, I just wanted to get this issue started to get the dialog going.

BrigadeHub is designed to meet some very specific goals:

• Be the external face for the brigade
• List and organize active projects
• Give new users a place to onboard [ or admins a place to easily onboard new members ]
• Show upcoming events and calendars
• Show Leadership / Contact info
• Brigade Blogging

Also, keep in mind that this project started as just me throwing ideas on the wall and seeing what stuck, and this stuck pretty quickly. Maybe going into a V2MOM round for the project might be a good idea, given how many people are starting onboard?

cc: @sfbrigade/core-website-tools @sfbrigade/project-brigadehub

We need a blog landing page, with all blog posts, and individual blog pages, as well as an edit page to manage posts as a whole and individually. Editing for this iteration should be in raw markdown.

Design should mimic http://kodujdlapolski.pl/en/blog/ and http://kodujdlapolski.pl/en/welcome-to-code-for-poland/ respectively.

Views:

• Front end editor
• Front end plain text to markdown renderer
• Add a title field to the form group

Update: I moved front end work into a subticket

The editor and front end renderer are done enough so that I can create a blog post and send it along through POST. However, the page needs to be styled so that it doesn't look all janky (with the button resting on the top of the embeddable editor). It would be nice to have flash messages to alert the editor.

I'm not sure what to do about images or if they should even be part of the alpha release. Imgur does have an API and the editor does have the ability to embed images by linking to them externally. I think what would be a good compromise for a rough draft of this feature is to just have a 'Help Me' tool tip or page explaining how to upload pictures to imgur and then link to them from the blog editing page. It's not perfect but it'll be a good start. Afterwards, we can look at image hosting. Keystone.js has a good solution to this coding up so I bet we could look through their code base.

Model:

• Model for storage
• Support for plaintext storage
• Support for HTML storage
• Validation on unique title
• Published? status so an editor can review his work before releasing the post into the wild

Ability to edit a post moved into a subtask.

Everything is working on the model side. I pulled in a unique validator library to validate title to be a unique field so we don't create duplicate documents. Need to write a createOrUpdate convenience function unless Mongoose already has one.

Controllers:

• Link to Model
• Redirect to appropriate page (possibly a preview page before publishing)
• Store blog content in session data so it isn't erased on false validation redirect
• Auto-save blog content

Controller code is boring. But one thing I do have to figure out is where best to redirect the editor after he/she creates a blog post. A confirmation page? Back to the blog post creation page? Probably going to send them to the published blog post.

We need a logo for this app, specifically for Github oauth profiling. We need a logo that is a 1:1 square logo, preferrably without text, and one that is the same square logo with text below and to the side (for blogs and nav bars, respectively).

Anyone with design experience is welcome to take a crack at this. I'd like to get 3-4 ideas rolling and have the @sfbrigade/project-brigadehub team vote on which we like the best.

Ideally, there will be two versions of the final, one for dark background, one for light.

It is imperative that this project is done with Accessibility in mind, at least for the supported themes. For that end, I propose we conform this project to WCAG standards, which I'll abridge below. This could be a good opportunity to find/build a linter to check the codebase for immediate issues like alt tags on images, etc.

Principle 1: Perceivable

Information and user interface components must be presentable to users in ways they can perceive.

• Guideline 1.1 Text Alternatives: Provide text alternatives for any non-text content so that it can be changed into other forms people need, such as large print, braille, speech, symbols or simpler language.
• Guideline 1.2 Time-based Media: Provide alternatives for time-based media.
• Guideline 1.3 Adaptable: Create content that can be presented in different ways (for example simpler layout) without losing information or structure.
• Guideline 1.4 Distinguishable: Make it easier for users to see and hear content including separating foreground from background.

Principle 2: Operable

User interface components and navigation must be operable.

• Guideline 2.1 Keyboard Accessible: Make all functionality available from a keyboard.
• Guideline 2.2 Enough Time: Provide users enough time to read and use content.
• Guideline 2.3 Seizures: Do not design content in a way that is known to cause seizures.
• Guideline 2.4 Navigable: Provide ways to help users navigate, find content, and determine where they are.

Principle 3: Understandable

Information and the operation of user interface must be understandable.

• Guideline 3.1 Readable: Make text content readable and understandable.
• Guideline 3.2 Predictable: Make Web pages appear and operate in predictable ways.
• Guideline 3.3 Input Assistance: Help users avoid and correct mistakes.

Principle 4: Robust

Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies.

• Guideline 4.1 Compatible: Maximize compatibility with current and future user agents, including assistive technologies.

We need to be running current version of library dependencies

So I wanted to get in text some of the stuff we talked about at the CfSF Core team retreat this past saturday. I had great conversations with @jasonlally and @LarryBafundo about what/where we want brigadehub to go, and I think we can start outlining a basic roadmap of next steps for the application.

Larry shared with us some of his research in regards to project lifecycles, shown below:

I think one of the problems we ran into when starting this is we tried to start in that red dot, like a lot of others. As @Judy5000 and @andrewmbacon both pointed out, we do need to define a few of the initial discovery steps that will guide how we go forward. Part of this was outlined in #40, and I wanted to set down a little more solidly what the core team is looking for from this project, and how we can meet that need first, then build out for ease of redistribution after that is reached.

The milestones on the roadmap that I'm proposing are as follows:

current versioning: 0.x.x

Alpha #51

We get a 1:1 feature parity with the current CfSF website. We build it as a replica, using the tools we have and implementing the appropriate content-management systems to maintain it as it is, but using the new auth and adding an admin backend. This will take the load off the W&T team for updating the content of the website, and at the very least, will be a good standalone application in its own right. Architecture should be built with additional features in mind, but focused on current website functionality. During this time, we should also be reaching out to other brigades, and seeing what it would take to entice them to make the move to brigadehub, and start adding those features to the next iteration enhancements.

The scope/goal for this release would be to replace the current CfSF website fulltime. Timeline I'd like to shoot for would be end of CodeAcross, but that's negotiable.

versioning: 1.x.x-alpha, 1.x.x-alpha.x, etc. (following semver)

Beta

We expand out features to include user onboarding, project matching, and any other additional functionality not currently present in website. This would include 1-click deployment to heroku, docker imaging, and any other devops-easing functionality as well. Theming should be included in this release. We should also be reaching out to other brigades during this time to see if anyone is willing to start playing with the application, and getting quality beta feedback for usage/features.

The scope/goal of this release would be to replace between 2-5 brigades websites, or at least have them install it to play with it. Timeline 3 Months (May 2016).

versioning: 1.x.x-beta, 1.x.x-beta.x, etc. (following semver)

Live

We expand our outreaching efforts, and try to get brigades across the globe to adopt the platform, actively talking with other leadership teams, and making sure to support/help when issues arise. We should be expanding out the theme library, with up to 5-6 separate themes for brigades to choose from, and perfect the deployment pipeline for the application. Additional discovery and feature expansion can be made after this point.

The scope/goal of this release, while lofty, would be to replace the websites of all brigades, or as many as we can get to adopt it. Timeline 6 months (Aug 2016).

versioning: 1.x.x-rc.1, 1.x.x, etc. (following semver)

We'll go over this roadmap this Wednesday during Hack Night, so any of you that can make it, please do. If we could also get @jasonlally and @LarryBafundo in on that convo for some historical and contemporary context, that would be spectacular.

Needs to sync events with meetup events, allow for display/edit

There should probably be a dedicated repo to this in each brigade's account (e.g. blog), and the posts should be able to differentiate between published and not (default to not, since anyone can open one, and an owner can add published when it should be live). Also the interaction of what open/closed should mean in the context of blogs should be discussed (refer https://github.com/mateogianolio/openblog for possible ideas)

see #45

All Alpha features should be listed under the ALPHA - v1.x.x tag, and be listed in the v1.0.0 (Alpha Release) Milestone.

• Blog List page #113
  • Dynamic population of list #91
  • Blog List Page Styling #95
• Manage Blog List #115
  • Manage Blog List Page Styling #97
• Single blog post page #92 #120
  • Individual Blog Page Styling #96
• Single blog post page Admin Edit #89 #122
  • Edit Individual Blog Page Styling #94
• Events page #56
• Events page Admin Edit #127
• Projects page #128
• Projects page Admin Edit #110
• Single project page #132
• Single project page Admin Edit #134
• About / Contact #55
• About / Contact Admin Edit #138
• Landing / Home page #54
• Landing / Home page Admin Edit #136
• Login page
• Login page Admin Edit
• User List / Management #165
• Account Management #112
• Brigade Management Admin Edit #119

Design will be mimicking Code for Poland's new website

_Any sub tasks for alpha should be listed in this page for reference_

EDIT HISTORY:

Edits by @therebelrobot, Friday Mar 4 2016, 11:27 am PT. For original post, see #51 (comment)

Edits by @therebelrobot, Sunday Mar 20 2016, 11:53 am PT. For previous post, see #51 (comment)

Needs to pull list of projects and info about them. This should be cross-referenced with the full list of repos in the brigade's github group, and marked accordingly.

https://github.com/codeforamerica/cfapi

Heroku pipelines are in alpha but pretty slick. This is how I have it set up for one project in Toronto:

https://github.com/patcon/tocityhall-api#deployment

fwiw, this process depends on the deploy button process (ie. an app.json file):
https://devcenter.heroku.com/articles/heroku-button

Not sure how/where we want to do this, but we should be using current language standards for this application. This may include a babel build step, we'll need to do research on that.

Allow people to view/interact with/sign up for the slack channel directly from the site. Refer #7

Post-login, notify project leads of new interests

I don't have too hard of an opinion here but thought it would make a decent topic for discussion. How do we structure this application? Given how potentially complex this application could be, it might be valuable to organize like this:

C:\Users\drfra\OneDrive\Documents\GitHub\calidrought
├──.settings
├──app
│  ├──routes
│  └──views
├──bin
├──config
├──doc
├──docker
├──kue
├──lib
├──model
├──node_modules
├──public
└──test

Where all express related code outside of the entry point is organized instead of app but all ancillary code or tools can be stored in a different directory. Food for thought.

Mocha + istanbul, I want to shoot for as close to 100% coverage as we can get realistically.

I've added the .csscomb.json file to the project, we just need to go through the template and ensure the styling conforms with it.

I realized with #32, and it's requirement of dropping the database prior to usage, that we should set up seamless MongoDB migrations for this repo. I am woefully unexperienced with migrations, so anyone familiar with this can jump in.

@spiffysparrow

There is a lot of 'extra' code from the Hackathon Starter Kit that we don't need since it included support for every feature under the sun.

• Identify what we need and what we don't
• Clean, clean, clean

We need a landing page for future events, with a calendar and list of upcoming events and how to RSVP/attend

• Calendar with events shown [https://github.com//issues/123]
• list of events below the calendar if JS isn't available
• integration with Meetup API to pull current events #6
• a way to subscribe to events or show interest [https://github.com//issues/124]

Design should follow the basic design principles of the other pages (Code for Poland relies on Facebook for events), so we'll be pulling elements from Google calendar's month view, as well as facebook's event list:

taking a page from Code for Boston's book

Review priorities

• current: Roadmap see #45. Given everyone is ok with what is in the roadmap, we'll need to see about:
  • Updating current issue list to reflect new roadmap milestones
  • Add any additional issues to get to alpha
• next: ramp up to be ready for codeacross and alpha milestone
• after:

Finish what's in progress

• Design / logo, #29
• Build out html/jade skeleton for alpha frontend
• Map out all the data structures we need to populate frontend
• SCM abstraction, #44

Help new folks pitch in

• Talk about any questions from the roadmap
• Help them set up development environment
• Start with Help wanted issues
• Next, help with new pieces of current feature
• After, start with a new feature

cc @sfbrigade/project-brigadehub

for these user roles:

• project lead
• core
• core lead
• superadmin

I was going through the wiki page and that is a lot of information on a single page.

Conform this project to feross/standard. We want to make sure the coding style is consistent across the codebase, and this is a brainless way of getting it done.

There are tools to autoformat, though we'd want to do them one file at a time and do manual testing after each one to make sure it's still performing the functions needed. If you need help finding one of those tools, let me know.

Events need to sync info from Google Calendars for display/edit