From d0a68e322e44df2c23cb635efa49b9d4b9eb4b8a Mon Sep 17 00:00:00 2001 From: Stephen Mizell Date: Sat, 29 Aug 2015 14:19:07 -0500 Subject: [PATCH 1/5] RFC for steps to move to Refract 1.0 --- text/0000-refract-1.0.md | 56 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 text/0000-refract-1.0.md diff --git a/text/0000-refract-1.0.md b/text/0000-refract-1.0.md new file mode 100644 index 0000000..2decbcd --- /dev/null +++ b/text/0000-refract-1.0.md @@ -0,0 +1,56 @@ +- Start Date: 2015-08-29 +- RFC PR: (leave this empty) +- Refract Issue: (leave this empty) + +# Summary + +The document provides some thoughts on how we can move forward to version 1.0 of Refract. This document is not proposing we move to 1.0 immediately, but to rather start putting steps in place to get us there quickly and being intentional about it. + +# Motivation + +As Refract is moving into production environments, we need to keep the following in mind: + +1. We want to have as a concise of a spec as necessary for newcomers +1. We want to introduce breaking changes thoughtfully, which is what SemVer encourages. We currently can't do SemVer correctly without moving to 1.0. +1. We want to start registering media types for Refract representations +1. Moving this to production means people are actually going to start using this spec in the wild, and we need to prepare for feedback + +With this in mind, I'd like to start now thinking through the steps on how to prepare. This design outlines some small steps. Additionally, this document is open to additional suggestions in what we can do. + +# Detailed design + +## Versioning Namespace Documents + +In addition to moving to 1.0, we need to actually start versioning namespace documents. The reason for this is that we do not want a breaking change in a namespace to require a major version bump for the entire spec. + +**Proposal**: Start versioning current and future namespaces. We can do this immediately. + +## Namespace Functionality + +The one area of Refract that we have not implemented in our implementations is namespaces. Currently, the design of namespaces mimics that of XML, but the way we have implemented it does not follow. In Refract, each element can have its own lexically-scoped elements as defined in its own namespace. This allows for namespaces to be defined and used deep within a data structure. + +Our implementations have diverted from this concept, and are rather relying on the document itself to define the elements includes. We still have namespaces, but the namespaces are not scoped within elements inside the document and are not explicitly defined in the documents. + +In order to get to 1.0, we need to think about whether we want to leave these kinds of things in the spec and change to them, or if we want to align the spec with what we've practically done. + +**Proposal**: Consider removing ability for namespaces to be lexically scoped on each element and make namespaces rather document-defined as we've done in our implementations. + +## Separating Out Serialization Formats + +An important concept of Refract is that it is a model for representing data structures and is not a JSON format. With that said, we do have two current formats as defined in the spec, and all examples in the spec use one of these formats. + +This decoupling I think is important, because it gives freedom to implementors to implement the best way they see fit in their language/platform, and it allows for other serialization formats to spring up that may be helpful to others. + +**Proposal**: Explain the difference in the conceptual model and the serialization formats, and potentially move these serialization descriptions to their own file in the spec repo, separating them from the main spec. + +# Drawbacks + +This could be considered to be premature. I am open to that discussion, and also to the idea of doing some of the things outlined above without having 1.0 in mind. + +# Alternatives + +We can extend the time we spend in pre-1.0 days. + +# Unresolved questions + +This document does not specifically address how we define namespaces, only to start the discussion on what to do about them. From 77a6f81f430739b9adaf2ddb2ea75c64448d6759 Mon Sep 17 00:00:00 2001 From: Stephen Mizell Date: Sat, 29 Aug 2015 15:06:33 -0500 Subject: [PATCH 2/5] Rename version to 1.0.0 --- text/0000-refract-1.0.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/text/0000-refract-1.0.md b/text/0000-refract-1.0.md index 2decbcd..b8851bb 100644 --- a/text/0000-refract-1.0.md +++ b/text/0000-refract-1.0.md @@ -4,14 +4,14 @@ # Summary -The document provides some thoughts on how we can move forward to version 1.0 of Refract. This document is not proposing we move to 1.0 immediately, but to rather start putting steps in place to get us there quickly and being intentional about it. +The document provides some thoughts on how we can move forward to version 1.0.0 of Refract. This document is not proposing we move to 1.0.0 immediately, but to rather start putting steps in place to get us there quickly and being intentional about it. # Motivation As Refract is moving into production environments, we need to keep the following in mind: 1. We want to have as a concise of a spec as necessary for newcomers -1. We want to introduce breaking changes thoughtfully, which is what SemVer encourages. We currently can't do SemVer correctly without moving to 1.0. +1. We want to introduce breaking changes thoughtfully, which is what SemVer encourages. We currently can't do SemVer correctly without moving to 1.0.0. 1. We want to start registering media types for Refract representations 1. Moving this to production means people are actually going to start using this spec in the wild, and we need to prepare for feedback @@ -21,7 +21,7 @@ With this in mind, I'd like to start now thinking through the steps on how to pr ## Versioning Namespace Documents -In addition to moving to 1.0, we need to actually start versioning namespace documents. The reason for this is that we do not want a breaking change in a namespace to require a major version bump for the entire spec. +In addition to moving to 1.0.0, we need to actually start versioning namespace documents. The reason for this is that we do not want a breaking change in a namespace to require a major version bump for the entire spec. **Proposal**: Start versioning current and future namespaces. We can do this immediately. @@ -31,7 +31,7 @@ The one area of Refract that we have not implemented in our implementations is n Our implementations have diverted from this concept, and are rather relying on the document itself to define the elements includes. We still have namespaces, but the namespaces are not scoped within elements inside the document and are not explicitly defined in the documents. -In order to get to 1.0, we need to think about whether we want to leave these kinds of things in the spec and change to them, or if we want to align the spec with what we've practically done. +In order to get to 1.0.0, we need to think about whether we want to leave these kinds of things in the spec and change to them, or if we want to align the spec with what we've practically done. **Proposal**: Consider removing ability for namespaces to be lexically scoped on each element and make namespaces rather document-defined as we've done in our implementations. @@ -45,11 +45,11 @@ This decoupling I think is important, because it gives freedom to implementors t # Drawbacks -This could be considered to be premature. I am open to that discussion, and also to the idea of doing some of the things outlined above without having 1.0 in mind. +This could be considered to be premature. I am open to that discussion, and also to the idea of doing some of the things outlined above without having 1.0.0 in mind. # Alternatives -We can extend the time we spend in pre-1.0 days. +We can extend the time we spend in pre-1.0.0 days. # Unresolved questions From c7caa20608ec43873d696c2b88b22542c38098e3 Mon Sep 17 00:00:00 2001 From: Stephen Mizell Date: Sat, 29 Aug 2015 15:07:07 -0500 Subject: [PATCH 3/5] Add comment about creating separate repos for namespaces --- text/0000-refract-1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-refract-1.0.md b/text/0000-refract-1.0.md index b8851bb..26c23be 100644 --- a/text/0000-refract-1.0.md +++ b/text/0000-refract-1.0.md @@ -23,7 +23,7 @@ With this in mind, I'd like to start now thinking through the steps on how to pr In addition to moving to 1.0.0, we need to actually start versioning namespace documents. The reason for this is that we do not want a breaking change in a namespace to require a major version bump for the entire spec. -**Proposal**: Start versioning current and future namespaces. We can do this immediately. +**Proposal**: Start versioning current and future namespaces and move each namespace to their own repo. We can do this immediately. ## Namespace Functionality From 743443ce2f225ab4f7098c8afe772d1ad9bb1547 Mon Sep 17 00:00:00 2001 From: Stephen Mizell Date: Fri, 15 Jan 2016 17:05:44 -0600 Subject: [PATCH 4/5] Update per current state of RFCs and spec. --- text/0000-refract-1.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-refract-1.0.md b/text/0000-refract-1.0.md index 26c23be..04f89d5 100644 --- a/text/0000-refract-1.0.md +++ b/text/0000-refract-1.0.md @@ -25,7 +25,9 @@ In addition to moving to 1.0.0, we need to actually start versioning namespace d **Proposal**: Start versioning current and future namespaces and move each namespace to their own repo. We can do this immediately. -## Namespace Functionality +## [Resolved] Namespace Functionality + +**This has been resolved by [RFC 0011](https://github.com/refractproject/rfcs/blob/master/text/0011-remove-namespacing.md)** The one area of Refract that we have not implemented in our implementations is namespaces. Currently, the design of namespaces mimics that of XML, but the way we have implemented it does not follow. In Refract, each element can have its own lexically-scoped elements as defined in its own namespace. This allows for namespaces to be defined and used deep within a data structure. @@ -33,8 +35,6 @@ Our implementations have diverted from this concept, and are rather relying on t In order to get to 1.0.0, we need to think about whether we want to leave these kinds of things in the spec and change to them, or if we want to align the spec with what we've practically done. -**Proposal**: Consider removing ability for namespaces to be lexically scoped on each element and make namespaces rather document-defined as we've done in our implementations. - ## Separating Out Serialization Formats An important concept of Refract is that it is a model for representing data structures and is not a JSON format. With that said, we do have two current formats as defined in the spec, and all examples in the spec use one of these formats. From e8a36292f6b98da7fc1caf92527281e4ff02127a Mon Sep 17 00:00:00 2001 From: Stephen Mizell Date: Mon, 2 May 2016 15:05:38 -0500 Subject: [PATCH 5/5] Update 1.0.0 RFC --- text/0000-refract-1.0.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/text/0000-refract-1.0.md b/text/0000-refract-1.0.md index 04f89d5..84c3dda 100644 --- a/text/0000-refract-1.0.md +++ b/text/0000-refract-1.0.md @@ -23,7 +23,7 @@ With this in mind, I'd like to start now thinking through the steps on how to pr In addition to moving to 1.0.0, we need to actually start versioning namespace documents. The reason for this is that we do not want a breaking change in a namespace to require a major version bump for the entire spec. -**Proposal**: Start versioning current and future namespaces and move each namespace to their own repo. We can do this immediately. +**Proposal**: Move all current namespaces to API Elements project. ## [Resolved] Namespace Functionality @@ -41,7 +41,13 @@ An important concept of Refract is that it is a model for representing data stru This decoupling I think is important, because it gives freedom to implementors to implement the best way they see fit in their language/platform, and it allows for other serialization formats to spring up that may be helpful to others. -**Proposal**: Explain the difference in the conceptual model and the serialization formats, and potentially move these serialization descriptions to their own file in the spec repo, separating them from the main spec. +**Proposal**: Explain the difference in the conceptual model and the serialization formats, and create serialization guidelines for full Refract. + +## Inheritance + +Inheritance can be handled differently depending on the context in which the element is found. This shows up in how we handle inheritance within the data structure elements (now in API Elements). + +**Proposal**: Explain inheritance in some way, either in the base specification or through some type of guidelines document. # Drawbacks