Add transformation guide

[gjtorikian]

This is a guide that builds off of https://github.com/atomist/docs/pull/287, and discusses code transformations.

It's very nearly complete, but there's one thing I couldn't figure out: how to access parameters within the generator function. I would like the users' provided repo name to be the replacing text. I see the default arguments showing up in the command:

atomist generate-node-express-project

Node Express Project

Options:
  --help, -h, -?        Show help                                                          [boolean]
  --target-repo
  --target-description
  --target-visibility
  --target-apiUrl
  --target-owner

But I don't know how to get at them! @jessitron, would you be able to help out by providing a small code example for that here? :pray:

[jessitron]

ok good news and bad news. The good news is, I got this working

The bad news is, it looks like this:

    transform: [
        async (project, papi) =>
            updateTitle("README.md", papi.parameters.target.repoRef.repo)(project, papi),
    ],

[gjtorikian]

What does papi stand for?

[ipcrm]

@gjtorikian https://atomist.github.io/sdm/interfaces/_lib_api_registration_pushawareparametersinvocation_.pushawareparametersinvocation.html

[jessitron]

OK, I just hit the release button on the markdown pack.

This is a better impl:

import { updatePageTitle } from "@atomist/sdm-pack-markdown";
...

    transform: [
        async (project, papi) => {
            await updatePageTitle(project, "README.md", papi.parameters.target.repoRef.repo);
        },
    ],

What i like about this is, it defines the transform as a function which does a named thing. This lets people do other things with the project, it's a place they can build from, which updateTitle was not, it could only do that one thing and didn't lead into "now make it do something else of your choice"

they'll still need introduced to the Project API, there's a page for that iirc

[gjtorikian]

Awesome, thank you for that, @jessitron. When you've got a chance I think this is ready for another review.

[jrday]

@jessitron is this ready to be merged or more review needed?

[jessitron]

@jrday I say merge it