[Docs] Add note on module development about the copyrights #26812

ryansb · 2017-07-14T15:32:52Z

SUMMARY

Coding guidelines has this already, but it's not in the docsite anywhere I could fine.

ISSUE TYPE

Docs Pull Request

COMPONENT NAME

docs

ANSIBLE VERSION

ADDITIONAL INFORMATION

gundalow · 2017-07-14T16:34:19Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -125,6 +125,15 @@ Include it in your module file like this:
    # ... snip ...
    '''

+.. note::


I think this needs moving earlier in the file and not as a .. note::
This document should be in the same order as the module file itself

abadger · 2017-07-17T13:17:11Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

+
+   - The copyright/license declaration should be ONLY two lines, not the full
+     GPL prefix. If you notice a module with the full prefix, feel free to
+     switch it to the one-line declaration instead.


Break this into two pieces. Copyright and license should be separate entries. Rephrase the second paragraph so it only refers to the license declaration. Can add a note as to why (not needed + modules are transferred over the wire so extra comments are inefficient.)

abadger · 2017-07-17T13:25:59Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -116,7 +116,24 @@ Include it in your module file like this:
 .. code-block:: python

    #!/usr/bin/python
-    # Copyright header....
+    # Copyright © 2017 [REPLACE THIS]


Invalid python :-) I'd use (C) here. Alternative is to use:

# -*- coding: utf-8 -*-

as the second line in the file.

abadger · 2017-07-17T13:28:29Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

+     line. This is especially true of rewrites, but original authorship
+     copyright messages should be preserved. If applicable, contributors may
+     have their rights assigned to their employer for example: "Copyright ©
+     2017 Red Hat, Inc."


Instead of talking about copyright assignment, maybe just talk about copyright holder? Or maybe we don't want to talk about rights and assignment and such at all? We decided that we're going to start using "Copyright (C) 2017 Ansible Project", for instance. Ansible Project isn't a legal entity so it seems to not be about copyright holder...

This matches what's in CODING_GUIDELINES.md as of July 2017

abadger · 2017-07-17T13:48:43Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

+
+The first 3 lines of every module should look the same. The first line is the
+shebang, but the next 2 lines are the important bit: copyright statement and
+license.


Don't mix code with copyright and license. Also don't use absolute line numbers. A coding declaration also gets thrown in here in some cases and there can be more than one copyright line. I think we should have copyright and license in separate subsections.

abadger · 2017-07-17T13:48:57Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

+.. code-block:: python
+
+    #!/usr/bin/python
+    # Copyright © 2017 [REPLACE THIS]


Use (c) instead of ©

abadger · 2017-07-17T13:59:04Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

+additions to the module are allowed to add an additional copyright line. This
+is especially true of rewrites, but original authorship copyright messages
+should be preserved. If applicable, contributors may have their rights assigned
+to their employer for example: "Copyright © 2017 Red Hat, Inc."


Still don't like this paragraph's phrasing. Perhaps more like this:

Every module must include a copyright line with the original copyright holder. Major additions to the module (for instance, rewrites) may add additional copyright lines but, pre-existing copyright lines should be preserved. Code from Ansible is standardising on using the line "Copyright (c) 2017, Ansible Project" which covers all contributiors. Any legal questions need to review the source control history so the copyright header does not need to be exhaustive.

What does "Code from Ansible" mean here? Is that "Ansible, the professional team that gets paid to write Ansible code" or "Code from Ansible contributors"? Maybe "The Red Hat/Ansible team is standardising ....." would be better?

abadger · 2017-07-17T20:41:14Z

We'd like it to mean Ansible contributors, I think. That's the message I got from last week's discussion of copyright and related links from @alikins. So Ansible/red hat would be the opposite.

…roject`

ryansb · 2017-07-18T13:49:23Z

I see what you mean. I added some more wording recommending that as the standard copyright header.

dharmabumstead · 2017-07-18T17:16:51Z

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

-is especially true of rewrites, but original authorship copyright messages
-should be preserved. If applicable, contributors may have their rights assigned
-to their employer for example: "Copyright © 2017 Red Hat, Inc."
+Every file with a copyright line with the original copyright holder. Major


Please change "with" to "should have"

ryansb requested a review from dharmabumstead July 14, 2017 15:32

ansibot added affects_2.4 This issue/PR affects Ansible v2.4 docs_pull_request needs_triage Needs a first human triage before being processed. support:core This issue/PR relates to code supported by the Ansible Engineering Team. labels Jul 14, 2017

gundalow reviewed Jul 14, 2017

View reviewed changes

s-hertel removed the needs_triage Needs a first human triage before being processed. label Jul 14, 2017

ryansb force-pushed the copyright-info-dev-guide branch 2 times, most recently from 749549a to 01f57d1 Compare July 17, 2017 13:14

abadger reviewed Jul 17, 2017

View reviewed changes

Add note on module development about the copyrights

0439fa5

This matches what's in CODING_GUIDELINES.md as of July 2017

ryansb force-pushed the copyright-info-dev-guide branch from 01f57d1 to 0439fa5 Compare July 17, 2017 13:45

abadger reviewed Jul 17, 2017

View reviewed changes

Add recommendation for standardizing on `Copyright (c) 2017 Ansible P…

cabcfd3

…roject`

ryansb requested a review from alikins July 18, 2017 13:49

dharmabumstead suggested changes Jul 18, 2017

View reviewed changes

ansibot added the needs_revision This PR fails CI tests or a maintainer has requested a review/revision of the PR. label Jul 18, 2017

ryansb added 2 commits July 18, 2017 14:21

s/with/should have/

b51e92d

Fix more unicode

a250713

ryansb merged commit beca565 into ansible:devel Jul 19, 2017

ansibot added docs This issue/PR relates to or includes documentation. and removed docs_pull_request labels Mar 4, 2018

ansible locked and limited conversation to collaborators Apr 26, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs] Add note on module development about the copyrights #26812

[Docs] Add note on module development about the copyrights #26812

ryansb commented Jul 14, 2017

gundalow Jul 14, 2017

abadger Jul 17, 2017

abadger Jul 17, 2017

abadger Jul 17, 2017

abadger Jul 17, 2017

abadger Jul 17, 2017

abadger Jul 17, 2017

ryansb Jul 17, 2017

abadger commented Jul 17, 2017 via email

ryansb commented Jul 18, 2017

dharmabumstead Jul 18, 2017

ryansb Jul 18, 2017

[Docs] Add note on module development about the copyrights #26812

[Docs] Add note on module development about the copyrights #26812

Conversation

ryansb commented Jul 14, 2017

SUMMARY

ISSUE TYPE

COMPONENT NAME

ANSIBLE VERSION

ADDITIONAL INFORMATION

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

abadger commented Jul 17, 2017 via email

ryansb commented Jul 18, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment