Behaviour of reuse addheader

[carmenbianca]

This issue outlines all the ways in which one might use reuse addheader, and what should happen in those cases.

1. Simplest case

This is a super straightforward case.

reuse addheader --copyright "Mary Sue" --license 0BSD myfile.py should add the header

# SPDX-Copyright: CURRENT_YEAR Mary Sue
#
# SPDX-License-Identifier: 0BSD

Should there be a confirmation prompt here?

2. Overwriting current year

Also a simple case.

reuse addheader --year 1984 --copyright "Mary Sue" --llicense 0BSD myfile.py should add the header

# SPDX-Copyright: 1984 Mary Sue
#
# SPDX-License-Identifier: 0BSD

3. Chaining copyright holders and licenses

You can repeat arguments.

reuse addheader --copyright "Mary Sue" --copyright "John Doe" --license 0BSD --license MIT should add the header

# SPDX-Copyright: CURRENT_YEAR John Doe
# SPDX-Copyright: CURRENT_YEAR Mary Sue
#
# SPDX-License-Identifier: 0BSD
# SPDX-License-Identifier: MIT

4. No arguments

The thing prompts you, maybe? This might be super clumsy though.

Everything between brackets is user input.

$ reuse addheader myfile.py
Who is the copyright holder?: [Mary Sue]
What is the license?: [0BSD]
SUCCESS MESSAGE HERE

5. Environment variables

Maybe we can set environment variables so that you don't have to be prompted. Kind of like a default setting for lazy users.

$ export NAME="Mary Sue"
$ export EMAIL="mary@example.com"
$ export DEFAULT_LICENSE="0BSD"
$ reuse addheader myfile.py

will add the header

# SPDX-Copyright: CURRENT_YEAR Mary Sue <mary@example.com>
#
# SPDX-License-Identifier: 0BSD

Should the user be prompted to confirm this?

6. Config

Maybe we could put some defaults in .reuse/config. Let's say that that file looks like this:

[reuse]
default_license="0BSD"

reuse addheader --copyright "Mary Sue" myfile.py should add the header

# SPDX-Copyright: CURRENT_YEAR Mary Sue
#
# SPDX-License-Identifier: 0BSD

Should the user be prompted to confirm this?

The default copyright holder CANNOT be in .reuse/config, because an individual's setting cannot be in the repository.

7. Use git config

Maybe some defaults could be taken from git config. Given a .git/config (or global gitconfig) like this

[user]
	email = mary@example.com
	name = Mary Sue

Then reuse addheader --license 0BSD myfile.py might add the header

# SPDX-Copyright: CURRENT_YEAR Mary Sue <mary@example.com>
#
# SPDX-License-Identifier: 0BSD

Should the user be prompted for this?

8. All of the above

Given a git config like this:

[user]
	email = mary@example.com
	name = Mary Sue

and environment variables like this:

export NAME="Jane Doe"
export EMAIL="jane@example.com"
export DEFAULT_LICENSE="MIT"

and a .reuse/config like this:

[reuse]
default_license="0BSD"

What happens if you type reuse addheader myfile.py?

What happens if you type reuse addheader --copyright "John Doe" --license "CC0-1.0" myfile.py?

[carmenbianca]

Accidentally posted the issue before it was ready. I edited it to be complete now.

The main questions, I think, are:

• Should the user be prompted to confirm?
• Should there be an option to "force" without confirmation?
• What is the "order of operations" for the configurations? What takes precedence?

[mxmehl]

1. Simplest case
   Should there be a confirmation prompt here?

No, I guess not. But we could introduce some flag which makes it more interactive, so asks more often. Just like rm -i in GNU ;)

4. No arguments

You also run reuse addheader without additional options in 5. Anyway, I would not make the interactive thing the default, but either show the help, or use the environment variables if existing.

6. Config
   Should the user be prompted to confirm this?

As above, with an additional flag. Other than that, I would just be verbose about what the tool has done. Same for 7.

8. All of the above
   What happens if you type reuse addheader myfile.py

Erm... Being interactive, so outlining which sources the user has, and letting them choose one source, might be the most sensible option here...

What happens if you type reuse addheader --copyright "John Doe" --license "CC0-1.0" myfile.py?

You mean, if the holder and license conflicts with the env/reuse/git configs? I would give preference to the explicit options the user gave when running the tool, so in this case John Doe and CC0-1.0

[carmenbianca]

I like adding an interactive flag. But then the default behaviour should never be interactive. Ergo:

Erm... Being interactive, so outlining which sources the user has, and letting them choose one source, might be the most sensible option here...

This shouldn't happen unless the -i flag is given.

One good way to solve 8 is by documenting a very clear "order of operations":

1. Command-line arguments
2. Environment variables
3. git config and .reuse/config (they don't conflict)

And always verbosely confirming what the tool has done, of course. Perhaps even specify where a certain option comes from (e.g., "Sourcing 'Mary Sue' from the environment variable $NAME"; "Sourcing '0BSD' from 'default_license' in '.reuse/config'"). But with better wording.

You mean, if the holder and license conflicts with the env/reuse/git configs? I would give preference to the explicit options the user gave when running the tool, so in this case John Doe and CC0-1.0

Agreed.

[carmenbianca]

Oh, I should probably add: The more I'm pondering environment variables, the more I'm hesitant about it.

The variable $EMAIL sees some use in some programs. Perhaps the user sets this to their personal e-mail address in their bashrc, and they may not want to use their personal e-mail for development. Having a separate $REUSE_EMAIL might fix that, but then you run into the scenario where a user has different e-mails for different projects.

git config and .reuse/config solve these problems much better.

[mxmehl]

git config and .reuse/config (they don't conflict)

Could you please explain why they don't conflict?

Oh, I should probably add: The more I'm pondering environment variables, the more I'm hesitant about it.

Good points. I would also prefer simplicity, so less options. However, having env variables would allow for some scripting cases. OTOH, one could easily do that with the command line options.

Shall we drop it but keep it in mind if there is some well-reasoned request?

[carmenbianca]

git config and .reuse/config (they don't conflict)

Could you please explain why they don't conflict?

git config deals with name and e-mail. .reuse/config will not deal with those under any circumstance. That is because .reuse/config is shared between all contributors to the project.

Shall we drop it but keep it in mind if there is some well-reasoned request?

+1

[mxmehl]

Are the discussed options already part of the current addheader function, or are there some cases missing?

[carmenbianca]

Most of it is not yet a part of the addheader function. I'm going to take a look at that today.

[carmenbianca]

The current behaviour is:

1. Implemented, no confirmation
2. Implemented
3. Implemented
4. Not implemented
5. WONTFIX
6. Not implemented
7. Not implemented
8. WONTFIX

Will create a new issue for the not-implemented bits.