This is the heart of the api's __finish_write_verb
        It was moved to phylesystem to make it easier to coordinate it
            with the caching decisions. We have been debating whether
            to cache @id and @dateCreated attributes for the annotations
            or cache the whole annotation. Since these decisions are in
            add_validation_annotation (above), it is easier to have
            that decision and the add_or_replace_annotation call in the
            same repo.

def annotate_and_write(self,  # pylint: disable=R0201
                           git_data,
                           nexson,
                           doc_id,
                           auth_info,
                           adaptor,
                           annotation,
                           parent_sha,
                           commit_msg='',
                           master_file_blob_included=None):
        """
        This is the heart of the api's __finish_write_verb
        It was moved to phylesystem to make it easier to coordinate it
            with the caching decisions. We have been debating whether
            to cache @id and @dateCreated attributes for the annotations
            or cache the whole annotation. Since these decisions are in
            add_validation_annotation (above), it is easier to have
            that decision and the add_or_replace_annotation call in the
            same repo.
        """
        adaptor.add_or_replace_annotation(nexson,
                                          annotation['annotationEvent'],
                                          annotation['agent'],
                                          add_agent_only=True)
        return self.commit_and_try_merge2master(file_content=nexson,
                                                doc_id=doc_id,
                                                auth_info=auth_info,
                                                parent_sha=parent_sha,
                                                commit_msg=commit_msg,
                                                merged_sha=master_file_blob_included)