Draft of js git commit convention

[dignifiedquire]

This is a first draft as discussed in ipfs/aegir#30.
It is very much based on the referenced angular commit convention.

Currently there is no mentioning of signing commits. The reason for this is that we would need to change the tooling first to remove those signatures from the changelog. So I want us to be sure we need and want to add this.

cc @diasdavid @victorbjelkholm @nginnever

[daviddias]

signing commits.. So I want us to be sure we need and want to add this.

I believe that 'eventually', we don't have a choice other to invite everyone to sign commits, but that might have changed. @jbenet thoughts?

[RichardLitt]

I'm not sure the bold adds anything, to any of these.

[dignifiedquire]

This is not written by me and left unchanged as much as possible from the angular commit convention document.

[RichardLitt]

My opinions are the same. I would remove the bold.

[dignifiedquire]

I think it's important to keep the emphasis on theses, but for that we should use italics rather than bold. Would that be okay for you?

[RichardLitt]

I don't feel that it is important to keep the emphasis. My reasoning is that I find it comes from a standpoint of lecturing, saying that this is how we do things. I think that because the emphasis is pseudo-random it also comes off as emotional - these words are important for me, as a writer, so I am going to make sure that I get them across.

I think it is more in the spirit of collaboration, and trusting the reader, not to put in these. I know this is a stylistic choice - @jbenet, for instance, really likes to use italics, bold, and headings as often as he can. In a styleguide, though, I think that it is important to nail this, as people will see this as a formal declaration, and any emotive writing that could be taken as aggressive, condescending, or bland needs to be avoided.

[RichardLitt]

I believe that 'eventually', we don't have a choice other to invite everyone to sign commits, but that might have changed. @jbenet thoughts?

I agree with this, and I don't think it has changed.

Good draft, @dignifiedquire. I think this would be a good place for us to start. We can iterate no this.

[RichardLitt]

This got lost in a comment, but I feel that it is important. It is what is holding me up from merging this. Can we talk about it?

---

I don't feel that it is important to keep the emphasis. My reasoning is that I find it comes from a standpoint of lecturing, saying that this is how we do things. I think that because the emphasis is pseudo-random it also comes off as emotional - these words are important for me, as a writer, so I am going to make sure that I get them across.

I think it is more in the spirit of collaboration, and trusting the reader, not to put in these. I know this is a stylistic choice - @jbenet, for instance, really likes to use italics, bold, and headings as often as he can. In a styleguide, though, I think that it is important to nail this, as people will see this as a formal declaration, and any emotive writing that could be taken as aggressive, condescending, or bland needs to be avoided.

[rjrotheryjr]

Hey Everyone IPFS Newb Here,

I wholeheartedly agree with Richard's last comment, "In a styleguide, though, I think that it is important to nail this, as people will see this as a formal declaration, and any emotive writing that could be taken as aggressive, condescending, or bland needs to be avoided."
The written language has standards, guidelines and rules. Perhaps a format would be chosen for the styleguide and other formal documents.

[daviddias]

@rjrotheryjr thank you for jumping and chipping in, that feedback was really valuable :)

[dignifiedquire]

@RichardLitt @rjrotheryjr thank you for your feedback. I honestly don't understand why you think that using italics as an emphasis, to help guide the reader through the text is considered emotional but I removed it for now as I would like to start using it and not be stuck here because of formatting differences.

[RichardLitt]

@dignifiedquire Might be worth talking to me about it, off thread. (See what I did there? :))

Thanks for this. Merging.

[rjrotheryjr]

@RichardLitt I had the American Psychological Association's (APA) format drilled into my writing while completing my undergraduate studies many moons ago. Frankly, I agree with the format. In reference to italics, the Style Manual of the American Psychological Association (APA, 2009, pp. 104-106) is very clear on the use of italics. Note especially the bold section (bold emphasis mine):

Use italics for

    titles of books, periodicals, films
    exception: italic words in the title (reverse italicization)
    genera, species, and varieties
    introduction of a new technical term
    (after a term has been used once, do not italicize it)
    a letter, word, or phrase cited as a linguistic example
    ("words such as big and little")
    words that could be misread
    ("the small group", meaning a designation, not group size)
    letters used as statistical symbols or algebraic variables
    some test scores and scales
    periodical volume numbers in reference lists
    anchors of scale
    ("health ratings ranged from 1 (poor) to 5 (excellent)")

Do not use italics for

    foreign phrases and abbreviations common in English
    chemical terms
    trigonometric terms
    non-statistial subscripts to statistical symbols or mathematical expressions
    Greek letters
    **mere emphasis. (Italics are acceptable if emphasis might otherwise be lost; in general, however, use syntax to provide emphasis.)**
    Incorrect:
    it is important to bear in mind that this process is _not_ proposed as a stage theory of developments.
    letters used as abbreviations

You will discover that I am a proponent of standardization. Standardization does not impede creativity, rather it challenges creators to be more creative within a set of guidelines.

Good To Be Here

[RichardLitt]

Might be a bit stringent for us, but a good guide!

[rjrotheryjr]

Understood ... food for thought.