Specification implementation examples

[chrissimpkins]

Perhaps as EXAMPLES.md and EXAMPLES.rst. Yeah I hate rst too but there is a PyPI cohort out there who might find it useful...

[kentcdodds]

👍 Maybe we should put it in a directory then: examples/markdown.md and examples/reStructuredText.rst

[chrissimpkins]

I likely won't get to a PR before this evening but I'm happy to submit it. If someone else is motivated, please feel free to have at it.

[chrissimpkins]

Wow. The pandoc conversion from Markdown to rst for a six wide table:

+--------+--------+--------+--------+--------+--------+--------+
| `|Kent | `|Divj | `|Ben  | `|Jame | `|Jero | `|Chri |
| C.     | ot     | Briggs | s      | en     | s      |
| Dodds| | Singh| | |\ Ben | Monger | Engels | Simpki |
| \ Kent | \ Divj | Briggs | |\ Jam | |\ Jer | ns|\ C |
| C.     | ot     |  <http | es     | oen    | hris   |
| Dodds  | Singh  | ://ben | Monger | Engels | Simpki |
| <http: | <http: | eb.inf |  <http |  <http | ns <ht |
| //kent | //boga | o>`__  | ://git | s://gi | tp://g |
| cdodds | s04.gi | `📖 <ht | hub.co | thub.c | ithub. |
| .com>` | thub.i | tps:// | m/Jame | om/jfm | com/ch |
| __     | o>`__  | github | skmong | engels | rissim |
| `📖 <ht | `📖 <ht | .com/k | er>`__ | >`__   | pkins> |
| tps:// | tps:// | entcdo | `📖 <ht | `📖 <ht | `__    |
| github | github | dds/al | tps:// | tps:// | `📖 <ht |
| .com/k | .com/k | l-cont | github | github | tps:// |
| entcdo | entcdo | ributo | .com/k | .com/k | github |
| dds/al | dds/al | rs/com | entcdo | entcdo | .com/k |
| l-cont | l-cont | mits?a | dds/al | dds/al | entcdo |
| ributo | ributo | uthor= | l-cont | l-cont | dds/al |
| rs/com | rs/com | ben-eb | ributo | ributo | l-cont |
| mits?a | mits?a | >`__   | rs/com | rs/com | ributo |
| uthor= | uthor= |        | mits?a | mits?a | rs/com |
| kentcd | bogas0 |        | uthor= | uthor= | mits?a |
| odds>` | 4>`__  |        | Jamesk | jfmeng | uthor= |
| __     |        |        | monger | els>`_ | chriss |
| 👀 ❓    |        |        | >`__   | _      | impkin |
|        |        |        |        |        | s>`__  |
+========+========+========+========+========+========+========+
| `|Kent | `|Divj | `|Ben  | `|Jame | `|Jero | `|Chri |
| C.     | ot     | Briggs | s      | en     | s      |
| Dodds| | Singh| | |\ Ben | Monger | Engels | Simpki |
| \ Kent | \ Divj | Briggs | |\ Jam | |\ Jer | ns|\ C |
| C.     | ot     |  <http | es     | oen    | hris   |
| Dodds  | Singh  | ://ben | Monger | Engels | Simpki |
| <http: | <http: | eb.inf |  <http |  <http | ns <ht |
| //kent | //boga | o>`__  | ://git | s://gi | tp://g |
| cdodds | s04.gi | `📖 <ht | hub.co | thub.c | ithub. |
| .com>` | thub.i | tps:// | m/Jame | om/jfm | com/ch |
| __     | o>`__  | github | skmong | engels | rissim |
| `📖 <ht | `📖 <ht | .com/k | er>`__ | >`__   | pkins> |
| tps:// | tps:// | entcdo | `📖 <ht | `📖 <ht | `__    |
| github | github | dds/al | tps:// | tps:// | `📖 <ht |
| .com/k | .com/k | l-cont | github | github | tps:// |
| entcdo | entcdo | ributo | .com/k | .com/k | github |
| dds/al | dds/al | rs/com | entcdo | entcdo | .com/k |
| l-cont | l-cont | mits?a | dds/al | dds/al | entcdo |
| ributo | ributo | uthor= | l-cont | l-cont | dds/al |
| rs/com | rs/com | ben-eb | ributo | ributo | l-cont |
| mits?a | mits?a | >`__   | rs/com | rs/com | ributo |
| uthor= | uthor= |        | mits?a | mits?a | rs/com |
| kentcd | bogas0 |        | uthor= | uthor= | mits?a |
| odds>` | 4>`__  |        | Jamesk | jfmeng | uthor= |
| __     |        |        | monger | els>`_ | chriss |
| 👀 ❓    |        |        | >`__   | _      | impkin |
|        |        |        |        |        | s>`__  |
+--------+--------+--------+--------+--------+--------+--------+

I'm thinking that we encourage use of Markdown with automated conversion to rst rather than providing rst templates...

[kentcdodds]

Lol, that's hilarious. I agree :-)

[chrissimpkins]

That is definitely not for human use... :)

[chrissimpkins]

#20

[chrissimpkins]

Pulling the discussion about PR #20 over to this thread based upon an attempt to manually mock the current spec for an example Markdown collaborator list.

@kentcdodds We are starting to delve into implementation issues here and, while not part of the spec, they will be important to how/whether projects use this spec. The change in the git commit based definition of "contributor" appears to be the issue of most significance in this project. Perhaps we bag these examples/recommendations and mandatory contribution category indicators altogether in favor of a much more permissive implementation approach that places this in the hands of the project where it likely belongs. As I understand the goal of this project, it is that all contributors who meet community defined criteria of this term (which is in flux and being worked out at present in this early draft version), are acknowledged for their contribution. Period. Whether projects provide an indicator of the type of contribution, an image that represents the contributor, and the way that they implement these indicators should perhaps exist outside of the spec itself or at the very least should be optional components of the specification and decisions for the project teams.

Thoughts?

[kentcdodds]

I think I understand the concern you're expressing. However I worry that if we don't give at least an example and some specific guidelines, projects will be less likely to adopt the idea. Without the guidelines, the spec is no longer a spec, but more of a blogpost about a good idea people should implement in some way.

[chrissimpkins]

I completely agree. I think that guidelines are useful to help with implementation. I am specifically wondering about the use of these as mandatory parts of the specification:

• Indication of the Contribution Category in text or icon image format using the defined Contribution Categories and/or Contribution Categories emoji images (see below).
• A link to the Contribution Category in text or emoji format using the defined Contribution Categories and/or Contribution Categories emoji.

As I worked with the Markdown example, it became clear that these items may pigeonhole the entire spec a bit. Should display of the types of contributions in a list of contributors be mandatory or should it simply be the inclusion of individuals in the list who meet the community defined criteria as "contributor"? If we choose the former, projects that do not fit the mold of a small number of easily displayed contribution categories per contributor will not bother with implementation of this (in its current form) and will therefore not be in compliance with the specification. If we choose the latter, there is much greater flexibility for a project to determine the hows of acknowledgment and this, in my view, opens the spec to a greater variety of project types and project maintainers. It really hinges on whether, and at what level of granularity, acknowledgment is going to be defined. Is there a lower minimum "level" of acknowledgment implementation that we can specify if this is felt to be an issue?

[kentcdodds]

Just to be clear, you're basically suggesting that we move those two bullet points to the optional section and that we allow people to comply to the spec even if they don't specifically call out the types of contributions people have made?

I think I'm ok with that. Thoughts from others welcome 💭

[chrissimpkins]

@fhemberger
@ben-eb
@Jameskmonger
@jfmengels
@bogas04
@frigginglorious

Thoughts about the issues in #15 (comment)?

I don't mean that we should avoid a set of guidelines and maybe even examples (where this originated) of the contributor list, nor that tools to support the specification and optional guidelines for contributor lists should be developed. I do think that if we pull ourselves out of mandatory hows of acknowledgment implementation this becomes an acceptable specification for a much larger group of individuals & projects. I would favor specifying the who.

[ben-eb]

Seems like being more permissive makes sense to me. For example, there might well be people who want to use GitHub style emoticons for contributors instead of Unicode, etc.

[jfmengels]

all contributors who meet community defined criteria of this term (which is in flux and being worked out at present in this early draft version), are acknowledged for their contribution. Period.

👍 The aim of the spec is IMO simply to indicate what should be done, in regards of recognizing contributors and "displaying" them, not how:

• Indicating what should be considered a contribution (code, docs, talks, translation, bug reports, ...)
• broad guidelines on how to make the contributors stand out (list them in the README, add a contributors section, ...)

That said, the rest of the work IMO is to set up easy guidelines/workflows so that respecting the spec does not become too much of a burden for maintainers:

• Give contributor list examples
• Give ideas of how to display contributors (emoji is one way, but just one potential way)
• Explore and document/provide friction-less workflows. We have already seen problems with conflicts in merges, and we should find ways to avoid that as best as possible. And neither maintainers nor contributors should also have to add themselves to a Markdown table, figuring out how Markdown works, why the display breaks when adding the 8th contributor or 4th contribution emoji.
  • Provide tools (well, that's why I started the CLI at least), GH bots, ...
  • Indicate how maintainers can communicate with the contributors in order to know how the user would like to get represented.

Not sure if you agree, but IMO all (or almost all) the work should be handled automatically or semi-automatically, I think it will otherwise be really too painful for maintainers.

In short: more permissive also makes sense to me (Sorry if I totally missed the point ^^')

[chrissimpkins]

we allow people to comply to the spec even if they don't specifically call out the types of contributions people have made

Seems like being more permissive makes sense to me.

The aim of the spec is IMO simply to indicate what should be done, in regards of recognizing contributors and "displaying" them, not how

I think that we are all saying similar things and it seems that there is some level of agreement about the laxity in the implementation / layout of the acknowledgments associated with the specification. If this is the case, should we create new issue reports for the mandatory parts of the spec in its current iteration so that we can discuss these in more detail to nail down the wording? It seems that there may need to be a bit of shuffle between what are currently considered mandatory and optional items. Perhaps we call those that deal with how one formats their contributor tables / lists "guidelines for implementation" and they exist outside of the spec altogether?

This would turn the spec into something that:

1. defines a contributor based upon community defined categories that represent contributions to open source work (as currently defined in the Emoji table & open to vetting + modification by the community)
2. specifies that all contributors should receive project acknowledgment as a contributor in some "prominent" way if they meet the definition of a contributor based upon add ${username}.png tip #1 above

The details of how the acknowledgment happens are then largely left to the projects that implement the spec, though we provide guidelines that might work for projects of various sizes/contributor numbers and suggest associated tools to ease the work associated with implementation of the spec (which is going to be a damn hard transition for many projects even if they are very motivated to support this!).

[kentcdodds]

I +1 the apparent general consensus :-)

[shockwavemoto]

@kentcdodds We are starting to delve into implementation issues here and, while not part of the spec, they will be important to how/whether projects use this spec. The change in the git commit based definition of "contributor" appears to be the issue of most significance in this project. Perhaps we bag these examples/recommendations and mandatory contribution category indicators altogether in favor of a much more permissive implementation approach that places this in the hands of the project where it likely belongs. As I understand the goal of this project, it is that all contributors who meet community defined criteria of this term (which is in flux and being worked out at present in this early draft version), are acknowledged for their contribution. Period. Whether projects provide an indicator of the type of contribution, an image that represents the contributor, and the way that they implement these indicators should perhaps exist outside of the spec itself or at the very least should be optional components of the specification and decisions for the project teams.

[kentcdodds]

I'm fine with that. Honestly I've focused more of my efforts around the all-contributors-cli project. The spec was originally created before that CLI existed. I'm looking forward to more automation to be written (like a GitHub bot that automatically updates the .all-contributorsrc and the README.md for us).

I'm less concerned about how folks implement this spec. I'm more interested in people get attribution for their work.

[Berkmann18]

@chrissimpkins Have you had a chance to prepare a PR for that?

[chrissimpkins]

@Berkmann18 Unfortunately I have not. Apparently three years was not sufficient time. :) My apologies.

Is this still something of interest? I have been following very peripherally and will need to catch up with where things are to submit this.

[Berkmann18]

@chrissimpkins It's still something of interest, have you looked at the website, the CLI and the bot?

[chrissimpkins]

have you looked at the website, the CLI and the bot?

Just checked out all of the links. Lots of work going on here. Looks great! 👏 to all of the contributors :)

It's still something of interest

I would be willing to PR in a set of mocked up example README docs that follow the spec if your request is to address the OP comment that I made. Does the CLI tool support *.rst as well as *.md files? If not, do you want *.rst too?

[Berkmann18]

I would be willing to PR in a set of mocked up example README docs that follow the spec if your request is to address the OP comment that I made.

Awesome.

Does the CLI tool support *.rst as well as *.md files? If not, do you want *.rst too?

It supports both (and possibly more but I only tested on both extensions).
I think having the *.rst one might be good for those who use those files like how *.md files are used on GH.

[Berkmann18]

@chrissimpkins Have you managed to get something working?

[lwasser]

hi colleagues @Berkmann18 @chrissimpkins i was digging around trying to find whether there is an .rst implementation (or markdown) rather than HTML for this bot. i use readthedocs which doesn't love html tables embedded within rst files. I may have missed this in the docs but is there a way to implement the bot so it writes the contributor table using rst or md? this issue suggests it may be possible?

thank you so much for any guidance. this is a super cool tool.

[Berkmann18]

@lwasser There's no option (afaik) for now that enables you to tell the bot which format to use but I reckon it would be a great feature to add.
Would you mind opening a PR for that?

[Berkmann18]

Friendly ping @lwasser .

[lwasser]

hey @Berkmann18 a PR for this is beyond my current tech skillset at the moment!! This is a great project however!

[melekler445]

Hey