I am working  on the versioning chapter for the book, and I am current at the place where I am suggesting letting the compiler know about what kind of situations your users are likely to get into.

The examples I am using is changing the API from:

requires @vacations

To:

requires @vacations, "Some explanatory text"

And handling the scenario where the user attempts to write to the old API.

Here is the default approach:

BCE0017: Boo.Lang.Compiler.CompilerError: The best overload for the method 'BDSLiB.QuoteGeneration.QuoteGeneratorRule.requires(string, string)' is not compatible with the argument list '(string)'.

We can use the standard [Obsolete] mechanism, like this:

[Obsolete("use requires(moduleName, explanation) instead", true)]
public void requires(string moduleName)
{
	throw new NotSupportedException();
}

And the error would be:

'BDSLiB.QuoteGeneration.QuoteGeneratorRule.requires(string)' is obsolete. use requires(moduleName, explanation) instead

This is still very scary message for non technical users. So we can up the cost a bit using this:

[Meta]
public static Expression requires(Expression moduleName)
{
	var message =
		@"
Requiring a module without supplying an explanation is not allowed. 
Please use the following syntax:
'requires " + moduleName + "', '" + moduleName + " is required because [add your reasoning here]'";
	CompilerContext.Current.Errors.Add(new CompilerError(moduleName.LexicalInfo, message));
	return new MethodInvocationExpression
	{
		Target = new ReferenceExpression("requires"),
		Arguments = new ExpressionCollection
		{
			moduleName,
			new StringLiteralExpression("No explanation specified")
		}
	};
}

In which case the error is:

BCE0000: Boo.Lang.Compiler.CompilerError:
Requiring a module without supplying an explanation is not allowed.
Please use the following syntax:
'requires 'scheduling_work'', ''scheduling_work' is required because [add your reasoning here]'

This is a much nicer message to get, I think you would agree.