CONTRIBUTING.md and CODE_OF_CONDUCT.md

[liclac]

We need contribution guidelines and a code of conduct before we start picking up any more contributors. I'll look into automatically enforcing these guidelines later - there are several bots that can do it.

(Ping @pnn in particular)

[ragnarlonn]

Nice! I just have two comments:

"until it's polished and perfect" - I don't like that wording. It gives a sense that we strive for perfection, which is never a good idea. I suggest "until it becomes good enough for inclusion into the code base", or similar.

On the commit format - quite a lot of commit prefixes people have to learn, and understand when to use. I suggest replacing "all commits MUST have..." with "all commits SHOULD have...". We should not force one-time or new contributors to learn a lot of complex rules before they can even start contributing. That may scare people off.

I like the CODE_OF_CONDUCT also.

[ghost]

other open source projects 😉

[ghost]

also i'd capitalize Contributor Covenant

[ghost]

closes it right away sounds a bit harsh, let's keep it at just closes it

[ghost]

we will

[ghost]

ideally, there should be a really basic explanation of git flow for folks that don't want to read a whole blog posts here. besides, only the concept of the develop branch and feature branches are relevant for this section

[ghost]

this could be an anchor link

[ghost]

nice

[ghost]

this could be clarified, i feel

[liclac]

How's this?

[ghost]

i just sort of wrote some notes down. besides those, i agree with what @ragnarlonn said

[bagder]

Wait, what? "develop" ? What's that branch and why is that used instead of master? That's highly unorthodox and if you'll keep that system I think you need to explain that here first and not take it for granted. Most git projects out there just use master as... eh, the master branch.

[bagder]

Is there some considerations regarding copyright that contributors should be aware of or adhere to?

[martinfijal]

To make it simpler for people wanting to contribute, I'd make the following changes:

• Drop the use of commit prefixes. We've used them internally for a while and I've yet to see any actual benefit to them.
• Drop the use of git flow and just accept pull requests straight to master.

[robingustafsson]

Nice @uppfinnarn!

I agree with @bagder's and @martinfijal's line of thinking that git flow is perhaps overkill for k6 and adds an obstacle for people wanting to contribute. I'd also be in favor of just accepting pull requests against master and then making sure releases are managed properly (tagging, changelog etc.).

On the subject of releases, we should perhaps state somewhere what the release policy is? Fixed cadence? Whenever a maintainer feels like it? That's something I look for when contributing code. When will I be able to use an official release rather than my branch/packaging of the lib/app.

I think commit message prefixes are a good thing as they help when scanning a commit list for particular types of commits or areas of change. Also handy when putting together changelog/release notes.

What about an AUTHORS/CONTRIBUTORS file or something to recognize contributors? Or is that something best left for release notes?

[ghost]

@robingustafsson regarding contributor lists, there's multiple ways to go about it. you could obviously keep a CONTRIBUTORS.md file in the project root, but personally i think it'd be better to manually keep a list of people that contribute frequently in the README.md, akin to how the node.js project does it.

[bagder]

For my projects, I've found that it makes a lot of sense to write the commit messages' first line pretty much as a line that perhaps could make it into the RELEASE-NOTES (since then it goes fast to generate that list). In the curl project, we then put that into a web page for every release.

Having the first line < ~60 columns is also good for when you do git blame etc on the code.

A recent example:

http_proxy: Fix tiny memory leak upon edge case connecting to proxy
    
Fixes #1255

The commit message template for the curl project says this:

---- start ----
[area]: [short line describing the main effect]
       -- empty line --
[full description, no wider than 72 columns that describe as much as
possible as to why this change is made, and possibly what things
it fixes and everything else that is related]
       -- empty line --
[Bug: URL to source of the report or more related discussion]
[Reported-by: John Doe - credit the reporter]
[whatever-else-by: credit all helpers, finders, doers]
---- stop ----

... then we have a script that automatically gathers all Authors, Committers and people mentioned in the above mentioned *-by:- lines and update the THANKS file accordingly based on that.

Me personally don't believe in separating frequent contributors from others in the THANKS/CREDITS file. Everyone who helps out deserves a mention. A single change can be worth more than 10 separate ones.

This is just input on what has worked for us. Not implying these must be followed by you.

[ghost]

yeah - on second thought, maybe it is better to list all contributors. the single-out-proficient-contributors approach would be better for projects with larger (think >500) contributors, i guess?

also, if we're sharing commit message strategies, on the jekyll project we generate a history file based on the pull request titles. the history document is altered by a bot on every branch merge. here's an example of this.

that all depends on how releases are being done though? a dedicated bot or script might be overkill at first

[ragnarlonn]

Just a general reflection: I think that last comment by @pnn touched on something that might be important to remember - if you're used to working in a large project (in terms of contributor numbers or lines of code) the processes used there may not be ideal for k6 at this stage. It is usually wise to keep things very simple at the beginning of any project, only adding complexity as needed.

[liclac]

There are some good points here, the big thing is that master should be kept usable, but looking at how we handle it right now, we just tag lots and lots of small releases to merge develop into master all the time.

Would everyone be for dropping the develop/master split, while still keeping the pull request model for new stuff?

[liclac]

How's this? When we merge, I'll get rid of develop and start taking PRs against master.

[ragnarlonn]

One very minor detail: we ask people to limit length of output lines (to terminal) to 80 characters, but maybe we should go for something slightly shorter. @bagder mentioned ~60 chars for commit messages and it appears that is about the recommended line length for best reading ergonomics - (https://en.wikipedia.org/wiki/Column_%28typography%29) Another benefit is that choosing a value a bit below 80 means people will be able to e.g. indent (for presentation purposes) k6 output with a few spaces without causing linebreaks on an 80-char display device.

[bagder]

We usually wrap commit messages at 72 actually, since "git log" in the terminal indents the commit messages a bit.

[liclac]

Hm, I usually prefer everything to be close to 80ch wide (accounting for indentation). Reading ergonomics is something very complicated (…that I've sunk an unhealthy amount of time into…), and varies by far more factors than just the width.

[ragnarlonn]

78? 72? I just think that if we aim to be 80x25-friendly we don't want to use 80-character lines when we output things. If we don't care about 80x25 (and frankly, is that important today?) we can choose whatever we want of course (though much longer than 100 chars is probably not good for reading ergonomics).

[liclac]

Mostly, all the terminals I know of (gnome-terminal, xfce4-terminal, iTerm2, Terminal.app, cmd.exe, I believe PowerShell too?) default to 80 characters wide.

But maybe leaving some margin wouldn't be too bad?