Understanding Data Source lifecycle

I’ve recently begun using the Terraform provider for GitHub, and I’ve found some areas I’d like to improve. Today I began experimenting with modifications to data_source_github_user, but the results weren’t what I expected.

In a brand-new directory, I setup a basic configuration with one instance of this data source, ran ‘init’, then ran ‘plan’, and as expected the attributes of the user were pulled from GitHub, but not stored in the local state file. I then ran ‘apply’, and the attributes were stored in the state file. So far so good.

Inside the code, I had added logging statements so I could see what was happening. On the first run, the code ran SetID() on the ResourceData structure, storing the GitHub numeric ID of the user. In the state file, I can see this stored in the id attribute.

On a second run of ‘plan’, the data source was invoked again to refresh the attributes, and I expected that calling Id() on the ResourceData structure would return the ID which had been stored using SetID() in the ‘apply’ operation, but it was not. Instead Id() just returned an empty string (or nil, I’m not sure which).

I need to modify the behavior of this data source so that it uses the numeric ID after it has been obtained on the first run; if the ID is in the state, the data source will behave differently than if the ID is not in the state. Unfortunately my assumptions about the lifecycle of the data source object seem to have been in error.

Are there documents which describe this lifecycle?