Consider a "towncrier init" subcommand

[tomschr]

Situation

Consider this use case: a developer wants to start a new project. Or another developer has an existing project. Both projects don't use Towncrier yet. In all cases, the user has to create the configuration file manually or has to read the documentation.

Proposed solution

It would be helpful, if Towncrier could create some default configuration. This could be done with a towncrier init subcommand. It could work like this:

1. Change to the project's directory.
2. Optionally create a virtual Python environment and install towncrier in it.
3. Call towncrier init. It will create a towncrier.toml file.
4. Optionally edit the towncrier.toml file (or leave it as is).
5. Job done! :wink:

Benefits

• Easier to use
• User doesn't have to read or remember all the config options.
• Faster (user doesn't have to search for the GitHub repo, open the README, read through it, apply it to its configuration...)

Questions

• Should Towncrier create a (default) directory for the news fragments? Like changes in the README?
• Should Towncrier ask for the project name, the package directory, the result NEWS file etc.? Or should it derive some parameters (from the directory or other files)?
• What default templates should be activated/enabled by default?
• Should the created default configuration should contain some comments to help the user?
• Should we allow to choose the configuration file? Or should it by default always towncrier.toml?
• What actions should be done when we encounter an existing pyproject.toml?

Synopsis

Usage: towncrier init [OPTIONS]

Options:
   --project PRJ   Name of the project name (otherwise derived from current directory name)
   --dir DIR       Directory name of the sources.
                   If the directory doesn't exist, it is created automatically and added a .gitignore file
   --start-version VERSION
                   The version to start with
   --template TMPL
                   The name of the template file

Maybe another option to enable/disable certain types could be useful. Not sure.

[adiroiban]

Thanks for putting this together.

The init can be an opinionated command. If I understand it right, the purpose of init is to get you up and running with as little documentation reading as possible.

I prefer to just call init without other questions.

If there is a question, I need to read the documentation and decide what I should answer.

Should Towncrier create a (default) directory for the news fragments? Like changes in the README?

Yes. I prefer it outside of src/ directory.

For my projects the dir is named /release-notes/. In this way, devs are reminded that the content of these files should be in the style of public / PR announcement and not commit messages.

Should Towncrier ask for the project name, the package directory, the result NEWS file etc.? Or should it derive some parameters (from the directory or other files)?

Is best if it can use packaging helper code to automatically detect from setup.py or setup.cfg

What default templates should be activated/enabled by default?

Should the created default configuration should contain some comments to help the user?

Yes.

Should we allow to choose the configuration file? Or should it by default always towncrier.toml?

Always towncrier.toml

What actions should be done when we encounter an existing pyproject.toml?

Always use towncrier.toml . If an existing towncrier.toml exist, abort :)

[tomschr]

Thanks for putting this together.

You're welcome. :slightly_smiling_face: Thanks for considering my idea.

The init can be an opinionated command. If I understand it right, the purpose of init is to get you up and running with as little documentation reading as possible.

Yes, that was the idea. Maybe we can allow more options to adapt some parts of the config file.

I prefer to just call init without other questions.

Sorry, I wasn't exact on this part.

The questions were meant as some discussion points IF you think this issue is somehow useful. :wink: To give you some further ideas which are dependent or related.

I didn't mean to use this questions to ask the user directly (although you could do that with some if you prefer that). Hope that clarifies it. :slightly_smiling_face:

If there is a question, I need to read the documentation and decide what I should answer.

That's correct. As said, it wasn't meant to ask the user directly, but maybe allow for some customization through options.

[...]

Should Towncrier ask for the project name, the package directory, the result NEWS file etc.? Or should it derive some parameters (from the directory or other files)?

Is best if it can use packaging helper code to automatically detect from setup.py or setup.cfg

That's the point. Not sure if this will work in all cases. Sometimes, setup.py / setup.cfg can be complicated beasts.

The simplest implementation would be to require some options. That would avoid complicated code and also avoid guessing.

What about this idea: as a first step, we could require some minimum options that the user has to pass to init. That makes the implementation easier. If we think this isn't enough, we could refine this behavior in a second step (another issue/pull request). Would that be an option?

What actions should be done when we encounter an existing pyproject.toml?

Always use towncrier.toml . If an existing towncrier.toml exist, abort :)

Good idea. :wink:

Thanks Adi for your reply! :+1:

[adiroiban]

That's the point. Not sure if this will work in all cases. Sometimes, setup.py / setup.cfg can be complicated beasts.

I guess that if you are just staring a project, you have a simple setup.cfg.

If your project is complicated... you can read the towncrier docs and figure out how to integrate it :)

We should not block the creating of an init command just because it will not work in all the cases.

What about this idea: as a first step, we could require some minimum options that the user has to pass to init.

Sound good.

[altendky]

Doesn't towncrier do on-the-fly name detection etc? So why are we also doing it up-front? As to asking the user questions, as long as you give a default then I don't see a problem with it. If they want to not care, they can press enter and accept the default. But... I'm not super excited about trying to work through the details, but I do think this command is useful, so I'll plan on being happy with whatever you two come up with.

[adiroiban]

I will never use such a command as I will rig my own build system and don't go with the default :)

I just left my feedback as I hope it can help with a future PR.

Even if I will not use init I can review such a PR. If there are no backward compatibility side-effects and this command will make other people happy, I don't see why we shouldn't have it.

so @tomschr you can design the init as you like :)