Helping newcomers contribute & helping dunai grow

[ivanperez-keera]

As some of you may have noticed, I've recently put in a lot of work into making sure that the code, and the process we follow, is thorough, clean, well organized. I'm paying a lot of a attention to software engineering matters, as (I hope) is evidenced by the several open issues that have to do with re-organization of the API, and the many closed issues that had to do with QA (e.g., testing, formatting guides). If you do a git log or open the repo with gitk, some of these matters should come across.

I'd like to facilitate people's contributions, and I want everyone to feel welcome to participate in the project. However, I've often found myself having to decline PRs and close issues without a solution, which makes me feel really really bad. Mainly, I've found myself declining PRs for two reasons:

• They were nice additions, but perhaps it's better they live in a separate library. Dunai is meant to be easily extensible, and that means, when someone wants a new instance, and new primitive or combinator, all they have to do is import dunai, extend it, and use it. The whole idea was that nobody had to re-implement the core, and they could publish their libraries that extended dunai without dunai having to change.

• They did not follow our process. We are using git flow with a few minor additions; all code conforms to a formatting guide, we need to show that it actually works, does not leak, etc.

So I'm reaching out to you for ideas. What can be done to maintain the exceptional level of quality we are striving to deliver, while facilitating code contributions and extensions, and encouraging people to join the dunai community?

[ivanperez-keera]

I have created the following issue template. This will request PR submitters to fill in several details before submitting a fix. Let me know if you have any feedback. There are some comments added using <!-- -->, view the comment in raw form to see those notes.

Description

Issue addressed

• #

Checklist

• I have personally checked all the items in the checklist below. I confirm that all items are ticked, the information provided is true and honest, and understand that, if I misrepresent my submission in order to get through the process more quickly, I may be permanently banned from contributing to this project.

Branches

• The code I'm requesting to pull is in a branch named develop-<descriptive-name>.
• The branch name contains no underscores.
• The branch has been rebased on top of the current develop HEAD.
• The code proposed addresses an existing, documented issue, completely, and ONLY one issue.

Code

• All code added conforms to the existing style guide.
• All code added is well documented.
• The code proposed compiles and passes the tests.
• All code introduced and new documentation are free from typos and grammatical errors.

Commits

• All commits included specifically pertain to the issue addressed. I have not included ANY commits that are not directly addressing the issue.
• The history of commits included in this PR explains how to solve the problem cleanly. There are no temporary commits, drafts, WIP commits.
• The last commit in this PR modifies the CHANGELOG, by either adding a new entry to the last group (if not yet released) or adding a new group (if one does not exist after the last release).

Commit messages

• All commit messages are free from typos and grammatical errors.
• All commit messages name the issue addressed with the text "Refs #<issue_number>." at the end of the subject line.
• The subject line of the commit messages is in the imperative form (e.g., "Add new function XYZ.", as opposed to "Added new function XYZ.").
• All commit messages name the package they apply to directly in the commit message with the notation:

<package_name>: <summary>. Refs #<issue_number>.

For example:

bearriver: Add new function XYZ. Refs #123123.

• All commits messages point to the same issue.
• All commits messages are descriptive and detailed, and include details in the message to help future developers and maintainers understand the changes proposed.
• The last commit in this PR, which modifies the CHANGELOG, has subject:

  <package_name>: Document changes in CHANGELOG. Refs #<issue_number>.