Merge into oam-browser or refactoring to simply a design guide

[tombh]

The main argument for making this a separate repo is for the ease of creating new side-projects to the main OAM project, such as; documentation, the uploader UI and imagery-coordination. Whilst I agree that a separate repo is the best solution for this, I've found that it creates more effort and technical debt than it saves.

I've been tasked with the building of user accounts for the OAM Browser. This has required merging multiple repositories (oam-uploader and oam-uploader-admin into oam-browser and also oam-uploader-api into oam-catalog), incurring significant development time. The difficulties of multiple repos has already been brought up elsewhere, by Development Seed and on the main repo here. The argument is stronger for HOT maintaining a design system like this, because of the possibility of fundamentally distinct projects with fundamentally different requirements. However I don't believe that is the case for OAM, I don't think any of the existing repos using the design system are so fundamentally different. The 3 remaining repos that use the design system are, oam-docs, openaerialmap.org and imagery-coordination, all which it easy to imagine being integrated with oam-browser. Furthermore the existence of a separate design system module only promotes the creation of further separate repos.

Here are some bullet point problems associated with maintaining this as a separate repo:

• Dependencies do not get updated when the downstream repo gets updated. So dependencies here are more likely to go out of date.
• Unique build conditions need to be maintained. Namely adding scss and image paths. And conditional paths for transpilers to reach in to node_modules/oam-design-system to build the ES6 code for use against node, therefore, when running tests.
• Adding a new SVG icon requires committing to a repository that is not the one you are developing, pushing this repo, updating a dependency on the repo your developing, then running npm install.
• Overriding styling is conceptually harder than editing styling.

None of these problems are at all insurmountable. However, I'd argue that in the long term, they create more work than they save. If the main requirement of this repo is to enable the creation of new applications utilising the OAM branding, then the same can be achieved with the simplicity of a conventional brand guide.

[mojodna]

We've been considering using this as the design basis of the new, React-based front-end for the Export Tool. As such, keeping it a standalone repository makes it easier to differentiate between what's design system-related and what's part of the tool using it. However, directing including it hasn't seemed feasible.

My preference would be for it to be refactored into a design guide w/ CSS, etc. that can be copied and adapted by projects that use it.

[tombh]

What's the Export Tool? Is that a non-OAM but still HOT project? If so then should OAM be responsible for HOT projects?

To keep to the original question though, will this save you more work than the extra work created for OAM maintainers?

[smit1678]

What's the Export Tool? Is that a non-OAM but still HOT project? If so then should OAM be responsible for HOT projects?

@tombh it's a HOT tool for exporting OSM data. His reference really refers to the HOT Design System which is a fork of the OAM Design System at the moment.

My preference would be for it to be refactored into a design guide w/ CSS, etc. that can be copied and adapted by projects that use it.

@mojodna @tombh Would it be helpful if it was a little more like Bootstrap (https://github.com/twbs/bootstrap) where it provides compiled CSS instead requiring you to include it as a module in your package.json?

[tombh]

Personally I'm not convinced a bootstrap-esque repo offers the kind of advantages needed to offset the maintenance costs of a separate repo. After all, a new external project (which OAM shouldn't really ever need as I pointed out earlier) can just copy and paste the SCSS from the main repo, which is not ideal, but it is a lot less work than maintaining so many distinct repos.

[smit1678]

@tombh @mojodna @sharkinsspatial Recapping our conversation last week. Post here if I'm missing anything that we discussed or agreed upon. I'm not sure if we fully came to a conclusion so offering a way forward (taking a longer term view here so I do acknowledge that there may be more overhead for a smaller team).

Review of the problem at hand:

• there is a need to not have to copy paste, but the overhead of javascript and dependancies is worth considering.
• managing a separate repo has costs when it’s not used outside of the main application or there is only a small team
• having a separate repo is nice for quick usability and ease of getting access to what you need
• a design system needs to have a style guide and assets for getting up and running quickly, not necessarily just an npm install method. Something like: http://vizzuality.github.io/gfw-style-guides/. Although an npm install method is useful in some situations.

A suggestion forward:

• look to add a style guide and compiled assets to the oam-design-system.
• keep the repo separate for future projects and to model how a design system can be used
• follow the principle that the design system is a style guide and that most custom implementations live within the application’s repos. Where there are styles or significant adjustments that need to be contributed back, make a pull request back into the design-system.
• version the design system so that changes can be tracked easily and projects that are using the design system know which version they are using

cc @ricardomestre @danielfdsilva if they have any input here

[tombh]

• Where there are styles or significant adjustments that need to be contributed back, make a pull request back into the design-system.
• version the design system so that changes can be tracked easily and projects that are using the design system know which version they are using

The point for me then is: who will do those things, or I mean who wants to do the above? I think we should be realistic and pragmatic and acknowledge that it's quite unlikely to happen. The fact is that the only active developers for OAM and therefore those who are affected by the implementation, are against the idea.

/grumble

[tombh]

Ok, to offer something a bit more constructive. Shall I stop using the design system as a formal dependency in oam-browser's package.json? I can just copy the relevant JS and CSS?

Then maybe all we need to do to this repo is update the README, to say that is essentially more of guide than a bootstrap-esque library?