How about adding a dedicated page with all the information about how to become a contributor? There's a lot of knowledge common for all rom-* projects so it feels wrong to duplicate it in CONTRIBUTING file in each repo.

This page could cover things like:

• Code style guidelines (probably boils down to "run rubocop" to get feedback however I'm worried that people might be pushed by rubocop to do silly refactorings like breaking down a method into 2 because some artificial limit is exceeded etc.)
• Basic design principles (avoid mutation, how OO is done in ROM, functional tidbits etc.)
• Support interface (Equalizer, ClassMacros, Options etc.)
• Git guidelines (esp regarding squashing, when to, when not to, what to write in commit messages)
• How to get help and support from core contributors
• How to find what to work on (it would be freaking cool to dynamically list issues tagged "help-wanted" there!)

We have a bunch of new features:

• defining root repos via Repository[:rel_name]
• commands macro
• aggregate interface

Original issue: rom-rb/rom#190

You can hide AR behind ROM. Let's document that.

We have a new schema dsl in core and rom-sql extends it with associate feature that needs docs.

Was just reading the ROM Rails tutorial and was confused by the term :tasks. Task can refer to rake/make tasks or batch tasks. I suggest changing all instances of :tasks to something like :todos.

It would be great to have a way of updating docs and tutorials during development so that it doesn't end up as a last big and overwhelming task just before a release.

First day ROMming. Reading the documentation, starting with the Setup guide ( http://rom-rb.org/guides/basics/setup/ ).

Is the code under "Defining Components" correct?

class Users < ROM::Memory[:memory]
end

Should that be ROM::Relation not ROM::Memory? Memory doesn't run for me, but Relation does (and makes more sense).

You can hide DM behind ROM for an easier transition. Let's document that!

Currently doc page titles only include the current doc title which isn't enough. We should prepend "Ruby Object Mapper | " to every page that doesn't have that.

• made with middleman
• hosted on github
• logo by Ben Darlow
• bootstrap theme flatly

Stuff to add:

• Brad's talk about AR vs Ecto http://confreaks.tv/videos/railsconf2016-activerecord-vs-ecto-a-tale-of-two-orms

This would help fill some of the gaps in knowledge around extensions and take some of the pressure off the contributors guide (see: #43), in terms of helping people to ramp up as contributors to ROM.

A guide should address the following details:

• The range of different possibilities for extending ROM
• The kinds of things that we want to see built
• High level description of the dataset and repository interface; examples from existing adapters
• Provided API hooks for extensions to work with
• How to write code that plays nicely with ROM
• Naming things
• Required git repo layout, gem spec, module, and testing structure

the link "Edit this article on GitHub" is broken because the repo is moved from https://github.com/tenjininc/rom-rb.org/ to https://github.com/rom-rb/rom-rb.org/

The copyright (c) on the site is currently “Ruby Object Mapper 2014-2015”. This is fine for now at a small scale, but as the site grows and more people contribute, it would be good to be very clear about how the content is made available.

One of the Creative Commons family of licenses (or a specific software documentation license) might be suitable here.

• https://www.gnu.org/philosophy/license-list.html#DocumentationLicenses

A content license basically reassures contributors that their contributions are covered by fair and well defined terms and will allow us to share and repurpose the content without running into copyright issues with text sourced from multiple contributors.

• switch to use rom migrations from rom-sql
• consider replacing Form with more idiomatic ROM code (needs discussion)
• update to rom 0.9.0
• consider using rom-repository rather than plain relations

We should use some JS thingy to convert nav into a hamburger mobile menu

Hello!

I know the design of the site is probably a low priority for ROM, but it's one way I could possibly contribute to the project. A welcoming landing page could entice more developers.

I created the attached designs in Sketch, but I can move forward into making this a full fledged site with Middleman.

Let me know if you would like me to move forward or hold off. Thanks!

Proposed info could include:

• List all the communication channels (gitter, forum, twitter etc.)
• Provide general information how to get involved, where to report issues, how etc.
• Links to contributing-related resources on website
• Section with a CoC

This should be discussed before any work starts. Please provide feedback in the comments of this issue.

I would like to add a section to the site where you can compare how you do things in ActiveRecord and what the corresponding code looks like in ROM.

In AR you would do this: [code]
In ROM it would look like this: [code]

This is a proposed structure for documentation on rom-rb.org. The content model provides a roadmap/demonstration of how to handle the long-term structure of the growing collection of content and how different topics can be represented.

Some of the names can potentially be changed around, but I think this is roughly what’s needed for 1.0.

Keep in mind that this is not about defining visual navigation on the site (though navigation should mostly be a product of the content model, there are a few contextual things that mean it’s not necessarily a 1:1 mapping). It’s also not an entire content strategy.

I haven’t addressed versioning, as I think it would be wiser to keep all docs unified around the current release state until after 1.0 has stablized and is more widely used (I am happy to elaborate on my rationale for this if people disagree—or see the notes on edge/experimental guides below).

About

High level overview of ROM, its structure, goals, and philosophy.

/about/introduction

What does ROM do? What problems does it solve? What does a ROM app look like?

/about/philosophy

Design concepts and rationale behind ROM. Features and tradeoffs. How it builds on previous ideas. Why ROM is not an ORM.

/about/glossary (/about/concepts)

Definitions of core concepts and vocabulary. All high level terms in ROM’s API should appear here (not just mappers, relations, commands, but also headers, datasets, etc). Should also include broader concepts and patterns that are relevant, like functional transformations, DCI, CQRS, etc.

/about/ecosystem

High level overview and map of the ROM ecosystem and how different projects fit into the whole. Could be included in the Community or Code sections instead.

/about/roadmap

Looking into the future. Could be included in the Community or Code sections instead.

Guides

Detailed developer reference that demonstrates how to use all the common (and not so common) features of ROM.

Basics

The basic stuff that everyone needs to know.

/guides/basics/setup (/guides/basics/registry or /guides/basics/env)

A guided tour of the setup and finalize hooks. The env registry could go here too, or could go in its own guide (same goes for setup DSL).

/guides/basics/relations

A guided tour of relations.

/guides/basics/mappers

A guided tour of mappers.

/guides/basics/commands

A guided tour of commands.

Adapters (Extensions? Plugins?)

These could also be at the top level (/guides/sql, /guides/mongo, etc).

/guides/adapters/memory

Using the memory adapter API in relations (restrict, project etc).

/guides/adapters/sql

A guided tour of rom-sql.

/guides/adapters/sql/relations

How to do various things with Sequel datasets and ROM.

/guides/adapters/sql/commands

How to do various DB specific things with commands.

/guides/adapters/sql

/guides/adapters/datamapper (/guides/adapters/dm)

A guided tour of rom-dm. Probably should mention “Datamapper 2.0” in an h1 for SEO purposes.

/guides/adapters/mongo

A guided tour of rom-mongo.

/guides/adapters/foo

etc...

Integrations (Plugins? Extensions?)

/guides/integrations/rails

Guide to all the features in ROM rails.

/guides/integrations/rails/generators

Listing of all provided generators.

/guides/integrations/rails/forms

Guided tour of ROM/Rails forms.

/guides/integrations/sinatra

How to integrate with Sinatra.

/guides/integrations/lotus

How to integrate with Lotus.

/guides/integrations/roda

How to integrate with Roda.

Advanced

Advanced and intricate stuff that is of special interest to document. @solnic to advise here.

/guides/advanced/aggregate-mapping

Stuff that is really not possible in other frameworks.

Edge (Experimental)

A place for experimental and changing features that aren’t necessarily baked into the core 1.0 API contract, but may be in future.

/guides/edge/try-either (/guides/edge/unsound)

Try/either semantics in commands. This may move into the core, but for now, it would be great to have it documented in brief (if it works!).

Internals

A guide to ROM internals and conventions. Mostly for people who want to contribute. Far less important than the guides listed above.

/guides/internals/adapters

A guide to writing adapters, repositories, datasets, using the linter, etc. (/guides/internals/linter could be its own guide as well).

/guides/internals/processor (/guides/internals/mapper)

Transproc, processors, the call convention, mappers, etc.

/guides/internals/conventions (/guides/internals/architecture)

Architecture/Ruby design conventions. Immutability, use of Equalizer, etc.

/guides/internals/testing

How testing works.

Tutorials (Examples, Samples)

Tutorials are written in a more conversational tone and assume less prior knowledge than guides. They’re beginner friendly, and provide step-by-step instructions for accomplishing specific things.

This could also be a subset of guides (/guides/tutorials). Or they could be pushed onto the blog (/blog/tags/tutorials).

The more I think about it, the less enthusiasm I have for tutorials. They are much more time consuming to write and maintain than guides, and they are generally only read once or twice when a reader is working through the examples, rather than referred to on an ongoing basis. If we were to name this section _Examples, we could potentially provide a mixture of short, example walkthroughs referencing GitHub repos like @gotar’s sinatra-rom project, as well as the existing tutorials described below._

/tutorials/rails-pet-store

Yes, I am literally (not figuratively) suggesting we replace the todo app with a contrived “pet store” sample domain model which harks back to the glory days of J2EE (disclaimer: not actually glory days). The “pet store” model is a subtle way of trolling Rails and DHH (but in a fun way, not a nasty way), while at the same time, provides genuinely useful examples of how to do more complex stuff like associations that the current tutorial overlooks.

/tutorials/sinatra-todo-api

A todo list API is ideal for demonstrating Sinatra.

/tutorials/adapter-from-scratch

See #51. It would be nice to work through a step by step example for connecting to a really basic data source (something like the todo.txt flat-file format which would be analogous to the existing CSV or YAML adapters, although less general purpose).

Code

Pointer to the source code and its dependencies.

/code/status

Status of projects in the ROM ecosystem and the latest release versions.

Community

All about people and communication, sharing and collaboration.

• Who ROM is (we are a group of users and contributors)
• The goals of the project (why we’re here)
• Why contribute? (you should join in too)
• How to contribute (next steps)

/community/contribute

Contributor information. Where to go and what to do. Sets high level expectations.

/community/conduct

A code of conduct. A starting point would be the Contributor Covenant which is included by default in Bundler generated Gems. See: #49

/community/press (/community/testimonials)

Good stuff that people are saying about ROM. Aspirational at this stage.

/community/events

Aspirational at this stage.

Blog

Its current use is more like a News section, but it can (and should) expand to cover various other things of interest, including use cases, links to cool stuff people are doing with ROM, mentions of edge API changes and experimental concepts, etc.

It would be a good to come up with some pre-defined main categories to use as tags, as this provides a clear template for contributions. Am open to people shooting this down as a bad idea, but I have provided some topic suggestions below.

Changelog

Consider merging the Release and Announcement tags into a single Changelog category. Alternatively, we could mix blog posts with the specific tags into a standalone Changelog page that also monitored GitHub activity. I prefer the blog approach though—simple and reflects what blogs do best.

Features

Explaining, clarifying, highlighting specific features and new capabilities in ROM. Answering common questions, and linking to docs, along with copious code snippets.

Case Studies (Examples?, Practice? In Practice?)

Stories about how ROM is being used in practice.

Events

Heads-up of upcoming talks and demos of ROM at Ruby events around the world. Also reviews or posts of slides/details from the talks.

Design (Architecture? Concepts? Articles?)

Software design articles and posts about conceptual and philosophical stuff, particularly areas where ROM is different from other libraries.

News, General

Maybe.

Repository examples from learn/reading/simple-objects are inherited from ROM::Repository::Base and looks like its deprecated

ROM::Repository::Base deprecated and will be removed in 1.0.0.
inherit from Repository instead

Documentation should be updated, OMW to fix this issue

Can't find link mentioned on this page:
https://github.com/rom-rb/rom-rb.org/blob/master/source/learn/advanced/flat-style.html.md

Rough organization:

Tutorials
  |- Rails
    |- Configuration & Setup
    |- Porting from ActiveRecord
    |- Migrations
    |- Relations in Controllers & Views
    |- Testing

The new website has not been published yet. Are there any outstanding tasks to be completed before updating it?

Roda is a tree based HTTP router/request dispatcher, similar to other HTTP microframeworks like Sinatra, Cuba, etc. Several people have mentioned they’d like to see more details about how to integrate ROM with Roda.

This tutorial has the potential to be an interesting alternative to Rails and Sinatra, perhaps written for a more advanced audience, with more detail about code organisation and application architecture for those who want to roll their own heavily customized/tailored app to fit their domain model. Or else, it could be as simple as a ‘getting started’ how-to tutorial.

A simple rails guide should include:

• information about initializer-based setup
• information about automatic setup when AR is present with database.yml
• information about directory structure for relations, mappers and commands

All of the above is covered by Rails tutorial but a simple guide will be better for now.

It's supposed to take page title by default and it doesn't seem to be doing that

The title on the page is defaulting to "The Middleman". Please add a default title.

Based on the feedback on reddit thread

There are situations where traditional ORMs would be difficult or unwieldy to use. Would be good to capture our ideas and provide more guidance as to how ROM can help.

Setup page
I initially thought the :sql in ROM::Relation[:sql] refers to what gateway the relation should use. The gateway method a few paragraphs down suggests that is not the case and I have to find out later.

Relations page
I really like the glossary.

Due to my lack of Ruby skills this line name_list = -> users { users.map { |user| user[:name] } took some time to process and in addition I think there is a } missing.

Combining relations sounds like a really important topic but the example line users.by_name('Jane').combine(tasks.for_users) is magic to me and I can only imagine what happens behind the scene or what the output looks like. In my mind I always tried to imagine how this combining looks like for example as SQL query. I'm not sure if I need to know this but currently it bothers me a little that I have this feeling of magic and not understanding.

Loading relations is also a little confusing. I think I understand it but I'm not sure what I would use in practice for what etc.

Mappers page
attribute :role # no coersion needed, this work is done by the mapper should this be :roles according to the previous examples?

Commands page
Why is .with used when combining commands, I think I see it the first time and wonder why this line
command = create_user.with(new_user) >> create_tasks.with(new_tasks) cannot be this command = create_user.call(new_user) >> create_tasks.call(new_tasks)?

Rails setup page have some missing parts. So below you'll find the things which are missing IMO

• using generators
• defining repositories
• defining forms
• Update ROM.container to ROM.env

Not sure if thats not the duplicate of #70 but here I'm mentioning only setup as such, not the tutorial. If it is a duplciate, please feel free to close this issue

The last example on http://rom-rb.org/guides/basics/setup/ raises ROM::Registry::ElementNotFoundError.

To reproduce:

# Gemfile
ruby '2.2.2'
source 'https://rubygems.org'
gem 'rom', '0.9.0.rc1'
gem 'rom-rails', '0.5.0.rc1'

# setup.rb
require 'rom'
ROM.setup(:memory)

class Users < ROM::Relation[:memory]
end

class CreateUser < ROM::Commands::Create[:memory]
  relation :users
  register_as :create
  result :one
end

ROM.finalize

rom = ROM.env

# access users relation
rom.relation(:users)

Run with bundle exec ruby setup.rb.

/Users/jared/.rbenv/versions/2.2.2/lib/ruby/gems/2.2.0/gems/rom-support-0.1.0/lib/rom/support/registry.rb:30:in `block in []': :users doesn't exist in ROM::RelationRegistry registry (ROM::Registry::ElementNotFoundError)
    from /Users/jared/.rbenv/versions/2.2.2/lib/ruby/gems/2.2.0/gems/rom-support-0.1.0/lib/rom/support/registry.rb:30:in `fetch'
    from /Users/jared/.rbenv/versions/2.2.2/lib/ruby/gems/2.2.0/gems/rom-support-0.1.0/lib/rom/support/registry.rb:30:in `[]'
    from /Users/jared/.rbenv/versions/2.2.2/lib/ruby/gems/2.2.0/gems/rom-0.9.0.rc1/lib/rom/container.rb:71:in `relation'
    from setup.rb:18:in `<main>'

I don't know if this is a docs issue or a regression in rom 0.9.0.rc1, but I'm being optimistic and reporting it here.

ROM consists of the core gem and adapters and it would be very helpful to show everything on one page along with version numbers and some information about stability of individual pieces.

For instance rom and rom-sql 1.0.0 will be released soon but rom-mongo will remain < 1.0.0 for a while. The same will happen with other adapters.

The example in the README and the diagram in the Overview don't show the domain model. This is pretty confusing, since the result in the example returns an instance of the domain model (Users in the example in the README). Adding the domain model to the diagram would help me understand better how ROM works with my domain model. Especially since Rails has given everyone the mind-set of thinking about the model as the primary focus. (I think it's likely that the whole point of ROM is to help developers focus on the domain model, by removing the persistence layers from the domain model.)

Since 0.6.0 is around the corner we should update tutorial before pushing the release so the site can be updated quickly

• update to use sub-classes of relation and mappers
• update to use Form objects (skip commands completely)