RS1: Package Organization

Issue

The organization and function of packages (such as packages/react-server-cli) are confusing and lead to some inflexibility. Further discussion can be found in #33, #65, #547, and #797.

The package organization is:

• babel-plugin-react-server/
• babel-preset-react-server/
• example-bike-share/ <= moved from react-server-examples/bike-share
• example-hello-world/ <= moved from react-server-examples/hello-world
• example-meteor-site/ <= moved from react-server-examples/meteor-site
• example-redux-basic/ <= moved from react-server-examples/redux-basic
• example-styled-components/ <= moved from react-server-examples/styled-components
• flab/
• generator-react-server/
• react-server/
  • All isomorphic components
• react-server-cli/
  • Command line functions only
• react-server-core-middleware/ <= move source to react-server
• react-server-data-bundle-cache/
• react-server-examples/ <= delete
• react-server-gulp-module-tagger/
• react-server-integration-tests/
• react-server-middleware-json-response/ <= move source to react-server
• react-server-module-tagger/
• react-server-redux/
• react-server-test-pages/
• react-server-website/

Decision

None

Status

Discussion

Detail

• Assumptions: Changing the organization and/or name of packages will be a breaking change for most users of react-server.

• Constraints: None.

• Positions: List the positions (viable options or alternatives) you considered. These often require long explanations, sometimes even models and diagrams. This isn’t an exhaustive list. However, you don’t want to hear the question "Did you think about...?" during a final review; this leads to loss of credibility and questioning of other architectural decisions. This section also helps ensure that you heard others’ opinions; explicitly stating other opinions helps enroll their advocates in your decision.

• Argument:

  • Having all of the examples under an examples directory prevents monorepo manager applications (like asini) from executing tests and keeping dependencies up to date. One example of this is changing all of the examples to rely on the newly published version of react-server at each release point. Hoisting the examples up to live directly under packages/ will enable the monorepo manager to manage them as well.

• Implications: A decision comes with many implications, as the REMAP metamodel denotes. For example, a decision might introduce a need to make other decisions, create new requirements, or modify existing requirements; pose additional constraints to the environment; require renegotiating scope or schedule with customers; or require additional staff training. Clearly understanding and stating your decision’s implications can be very effective in gaining buy-in and creating a roadmap for architecture execution.

• Related decisions: It’s obvious that many decisions are related; you can list them here. However, we’ve found that in practice, a traceability matrix, decision trees, or metamodels are more useful. Metamodels are useful for showing complex relationships diagrammatically (such as Rose models).

• Related requirements: Decisions should be business driven. To show accountability, explicitly map your decisions to the objectives or requirements. You can enumerate these related requirements here, but we’ve found it more convenient to reference a traceability matrix. You can assess each architecture decision’s contribution to meeting each requirement, and then assess how well the requirement is met across all decisions. If a decision doesn’t contribute to meeting a requirement, don’t make that decision.

• Related artifacts: List the related architecture, design, or scope documents that this decision impacts.

• Related principles: If the enterprise has an agreed-upon set of principles, make sure the decision is consistent with one or more of them. This helps ensure alignment along domains or systems.

• Notes: Because the decision-making process can take weeks, we’ve found it useful to capture notes and issues that the team discusses during the socialization process.