Making a contract for contract first development

In case you are not familiar with contract first development and why you should be doing it. I would suggest you read my article Understanding Contract First Development and Why You Should Consider It before you read this.   

Scaffolding out your contract is an art and one that you constantly practice and refine to the project at hand.  The more information you can define up front, the faster and easier your development will be. For example, you want to make sure you model not only the fields but also any additional qualities that the fields might need or use. This could be help text, a default value, or defining where the data that populates this might live. Let's take this one step further and also define some meta characteristics of the feature as well. These could be things like which module this is going to live in or the name.   

I am going to show you how we handle the contract creation process for the Sitecore CMS but many of the aspects described here are universal regardless of the platform or project. So please feel free to pick and choose or even add to this if you find yourself needing more information. 

Top Level Component Information 

First, we track the approvals from stake holders in a table. In our case that is the UI team, the BA team and the Sitecore team.  Really, we just need a lead or senior member of the team to look over the proposed contract and approve. We also track the contract status.  A contract is not considered done until the approval boxes are dated and digitally signed. 

                                                                                                                                                                                              Below we have the meta data section of the contract:           

Metadata 

Module: <module name> 

Placeholder: <placeholder name(s)> 

Component Name (Display Name): <component name> (<display name>) 

Datasource Template Name: <template name> (<display name>) 

Datasource Option: Auto-populate or a shared datasource folder

First, we have the module field and that is going to tell the developer where this component will reside in the project taxonomy.  Then we label any possible placeholders that this component can be placed into. Then (they say naming is the hardest thing to do in programming) declare the component, template, and display name.  Finally, as an example of tailoring your contract creation process to the task at hand we set a flag in the contract letting the developers know how it should act in our CMS.  That is whether we automatically create and set datasource for the rendering or pick an existing one.   

Layout Service Placeholders 

Below that we begin to set the fields and data that this component is going to return. We start with any placeholders that this component might contain.  In our case we call these “layout service placeholders” and use a table like this. 

 You will notice in the tables we use to define the data contract that there is an “RD ID” column. We affix a requirement ID to each entry that shows where the various parts of the contract's requirements come from, and you will see this repeated across the other tables.  The “RD ID” table will be discussed more towards the end of this process.  Then we have the name, what can go inside of it as well as any possible notes that may be relevant. 

Fields 

Next, we need to list out the fields that are required for the component to work. 

Once again, we have the requirement ID or RD ID column. Next is the “Field Name” -  It is important to make sure you pick a variable naming scheme and stick to it across all contracts.  “Field Type” should tell the developers what kind of data this is. Whether this is a single line text, a multilist, a link, a rich text editor etc.  The “Standard Value” column should contain the default value your front end is expecting if any.  The “Source” field should have the path or location to where the data that goes into this field is stored or lives.  “Help Text” should be any additional info that is needed to clarify the purpose of the field. Finally, “Notes” can be used purely as an informational source when referenced by developers during implementation.   

Parameters 

Parameters or Rendering Parameters are fields on a contract that do not hold content but instead decide the presentation or control how the data should be presented.  These are set on a component-by-component basis. This section uses the same table format as the “Fields” section. 

Sample Layout Response 

The sample layout response should be added after the contract is implemented and is a reference point for the front end.  This should be updated whenever the contract changes. 

Requirement Documents 

The last section is for your bookkeeping.  For each requirement document you draw from, attach an ID and the link or source of it in table.  Then using that ID you can now label the above sections. This is a great way to track the requirements as you abstract and collect them into a new document. 

While this process is specific to Sitecore, you can customize this process to meet the needs of your specific project. Afterall this is not a one size fits all solution and I just hope that you take some inspiration to make your projects even better.