Contribution guidelines

[mstenta]

I've been talking with @kadaan in IRC about the need for a more official "farmOS Contribution Guidelines" document, outlining some of the standard practices we employ in farmOS development.

I am starting to sketch up a list of things I think should be included. I will post here soon...

[mstenta]

opensource.com has a nice write-up on how to make effective guidelines for open source projects: https://opensource.com/life/16/3/contributor-guidelines-template-and-tips

[mstenta]

Here are some notes I've taken so far... just a brainstorm - needs to be organized, and some of these might be able to be combined...

• Drupal coding standards
  • stick with the best practices as much as possible, so that everything is easier to read, as long as you are coming at it from the standard practices
  • use code sniffer http://drupal.org/project/coder
• the less custom code the better
  • always start with existing contrib modules, active well-supported projects are best - try to predict future to avoid headache of moving to a new module if one no longer meets our needs or is abandoned
  • less custom code == less for us to maintain
  • every line of code should be justified (see comments rule below)
  • think of farmOS as a thin layer of connective tissue holding together all the component modules - the thinner the better - only what we need
  • this means we sometimes need to make hard decisions about what to include and what not
• the less dependencies the better
  • similar to above
• Features
  • always defer to Features exports - only override manually when necessary, justification will be required
  • this provides a level of standardization - offloads a lot of the code formatting decisions to the Features module (and config management in D8), which have a lot of decisions baked in - there is no reason for us to diverge from this
• focused granular commits - the more the better - commit messages that clearly "tell the story"
  • ideally each commit should work - even if it is one step in a series of commits - it shouldn't break anything - test each change before committing
• comment EVERYTHING
  • just because code is readable does not mean it is understandable
  • the intention is a lot more important than the outcome
  • "why" is just as important as "what" (if not more important)
  • don't just describe what the code is doing - explain WHY it needs to do that
  • again, going back to the custom code rule above - every line should be justified
  • note that this does not apply to automatically-generated code from Features (see: "do not modify the features-exported code unless necessary")
• consistency across modules
  • if adding a new field to a log type, should it be added to all log types?
  • how does this change relate to and/or affect other features in farmOS?
• naming conventions
  • prefix with "farm_" in general, to avoid conflicts with Drupal contrib (non-farmOS specific modules/features)
  • always think to the future - could the name conflict with something later?
• focused modules
  • keep each module as simple as possible/reasonable (obviously this is open to interpretation and discussion on a case-by-case basis)
  • don't pack too many things into one
  • many modules is not a bad thing!
  • if a feature might not be needed by everyone, put it in it's own module so that it can be turned on/off as needed
• misc:
  • base field definitions that are common across multiple farmOS modules should be defined in the farm_fields module (http://drupal.org/project/farm_fields)
  • ...

[kadaan]

Your initial contribution info looks good. Would like to put together a recommendation of tooling for contributors so that we all know how to setup the environment, start the app, debug, etc. PHPStorm seems great, but unfortunately it is a paid-for product.

I also think it would be good to incorporate as much of the verification into a travis (or similar) build that automatically happens for PRs. See: https://github.com/wp-cli/wp-cli/blob/master/.travis.yml

I'd also like to stress the importance of testing. Even though we are not at D8 yet, testing can still be done: https://www.lullabot.com/articles/write-unit-tests-for-your-drupal-7-code-part-1 & https://www.lullabot.com/articles/write-unit-tests-for-your-drupal-7-code-part-2

[mstenta]

Yes absolutely! Automated testing is a big priority in the 8.x-2.x branch. That was a huge initiative in Drupal core itself, in both the 7.x branch and even more so in the 8.x, and a lot of the testing infrastructure is built-in. Having automated Travis tests would be great! I have very limited experience setting up Travis config, so I would welcome help with that!

[mstenta]

This might have some ideas to incorporate: https://www.lullabot.com/articles/guidelines-for-writing-proper-tickets-and-commits

[jgaehring]

@mstenta, @alexadamsmith and I were talking about this topic today, with a particular focus on how to gather feedback and contributions from non-developers. The general question was...

How do we structure the feedback we're receiving from users so that we can later process that feedback in a meaningful way, quantify it along with feedback from multiple other users, and take action on that feedback in the future (ie, develop new features that have the highest priority within the community)?

After discussing various options, we decided that ideally the solution would not involve bringing in extraneous software stacks that would require maintenance and buy-in from existing users; instead we favored using our existing tools and just formalizing the process, and communicating better how it works to users.

Chief among these existing tools are GitHub issue queues. They provide a lot of flexibility and features that we're already leveraging, and most importanly, they already fit nicely into our standing workflows. They also have additional features we're not yet taking full advantage of, like issue templates. So one possible strategy I proposed was to create some templates, and then link to them from https://farmos.org/community/contribute/. On that page we could also provide some explanation of how GH issues work generally, as well as some pointers for how to use issue tags, upvote existing issues and comments, subscribe to issues, etc, etc.

[GerMarsh]

Even some developers - like this old fella - are not that familiar with GitHub so we could do with an overview! From what I have seen so far I understand why it is so popular for collaborative working.

[slarmour]

As far as reportimg issues goes, isn't that already done through the drupal page?

[mstenta]

@slarmour - Yea we're trying to strike a balance between "technical" issue management and also having a place for general questions, ideas, etc. In practice, I have been using drupal.org for specific technical issue management for the farmOS Drupal distribution code (the bulk of the project). At the same time, I've been encouraging people to post stuff here in GitHub as a starting point. Then what I'll do is create more specific issues in drupal.org for the actual development process. So I think we're talking about formalizing that workflow a bit more - so that this repo's issue queue can become more of a general starting point for farmOS discussion/questions/ideas - and then we can move/copy those to more specific issues elsewhere (drupal.org for farmOS core, but also https://github.com/farmOS/farmOS-client for the mobile app stuff, and others as needed).

[jgaehring]

I want to follow up here with some of the ideas we expanding upon in the monthly call, regarding the above comment...

A lot of people agreed that GitHub can be intimidating, but I think there was a general consensus that with the right sort of introduction to it could be made much more approachable. We also discussed the idea of having a guide to GitHub for farmers, updating the "Contribute" page in the farmOS docs, using GitHub labels for different topics like perhaps an FAQ label, using GitHub for broader community discussion about farming.

NEXT STEPS

• Update the Contribute page
  • Intro to GitHub for farmers
  • Link to the GitHub issues page
  • Links to create new issues (via templates, see below)
  • If possible, a preview of GitHub issues?
• Alex will create a screencast video for how to contribute to the farmOS documentation
• Jamie will create some issue templates
• Come up with some GH labels which could be useful for non-devlelopers

If other folks have additional ideas, please comment below!

[mstenta]

Great thanks @jgaehring !

I'd also add to that: we should add a CONTRIBUTING.md file to all relevant repositories, that includes both a link to https://farmos.org/community/contribute AND any project/repo-specific contribution guidelines, like the ones I outlined for the farmOS codebase in my comment above.

Thus, the CONTRIBUTING.md file can point people to both the general guidelines for the farmOS project as a whole (on farmOS.org), and also contain anything specific to the repo that the file itself lives in. So farmOS-client can have slightly different details in it than farmOS, such as stuff about linting, etc. How does that sound?

The other side-effect of this is that GitHub automatically detects these files and will display a link to them at the top of the issue page.

[mstenta]

Here's an example of what CONTRIBUTING.md (as well as issue templates) looks like inside the Ansible repo: https://github.com/ansible/ansible/tree/devel/.github (Note that they are all contained within a .github folder in the project root.)

And then at the top of the issue queue you can see the link to it: https://github.com/ansible/ansible/issues

[mstenta]

Perhaps in the other repositories (farmOS-client, farmOS.js, farmOS-aggregator, etc) we can also include a standardized message in CONTRIBUTING.md that says something to the effect of:

Only use this issue queue for development specific to farmOS-client. If this is a general farmOS question or inquiry, or you aren't sure where it belongs, use the farmOS issue queue instead. Maintainers will move or link issues as needed.

[kadaan]

Adding CONTRIBUTING.md under .github is non-obvious. Feels like it should be in both places, with a symlink.

[mstenta]

@kadaan Agreed - and it's not Github specfic. Maybe it also works in the root - I think I've seen repos that have it in the root. We can test that in a fork first.

I wouldn't mind doing that for CONTRIBUTING.md. The others (issue templates) should go in .github since they are GitHub specific.

[kadaan]

I was only really worried about CONTRIBUTING, README, and CODE_OF_CONDUCT. The issue templates should totally be in .github.

[kadaan]

BTW, can this all be tested in Travis???

[mstenta]

BTW, can this all be tested in Travis???

farmOS-client has a todo for that (adding tests to existing codebase): https://github.com/farmOS/farmOS-client/issues/33

I'm hoping to add automated testing to the server as well in the D8 upgrade - we rely mainly on upstream code, which is covered already, but there is custom code in the farmOS distribution modules that should have tests. D8 offers a more standardized way of doing this, so I'm hoping we'll have an opportunity to do it together.

[jgaehring]

I love seeing what Ansible is doing (332 issue labels?!?); however, I think they have some different goals from what ours would be. They're dealing with 1,676 pull requests and trying to moderate a very active pool of developers, whereas we are trying to encourage farmers to participate in the issue threads. I think if a farmer navigated to our issues and saw something like this, that would intimidate them. I think that's all the more reason to use the Contribute page as a gateway.

Thinking about that now, are we even sure we want to put this all in the Contribute page? If you're a farmer who's using farmOS and want to give feedback, are you going to know to look in Community > Contribute? Seems fairly intuitive, but is it obvious enough?

[jgaehring]

@kadaan if you have experience with Travis or some other automation tools that could help us with this, I'd love to enlist your advice on some of this stuff.

[mstenta]

I think if a farmer navigated to our issues and saw something like this, that would intimidate them

Haha yes. In our case that kind of technical stuff will be in different repos/issue queues, so I think we're safe in that regard. But... we may outgrow Github quickly (for general discussion) and that's fine too... let's see how it goes.

Thinking about that now, are we even sure we want to put this all in the Contribute page?

Good question - I think as long as we are consistent everywhere else about where we point to, we'll be fine.

[kadaan]

I do have experience with that. I might be able to help.

[GerMarsh]

I need to get some info together rather quickly as I am being invited to a workshop with local farmers (in West Wales) where farmOS will be compared with similar systems - commercial and otherwise. I would prefer to mindmap farmOS' functionality and architecture but anything in Powerpoint would be useful too.

[mstenta]

@GerMarsh Feel free to screenshot some of the slides from the recent PASA workshop: https://farmier.github.io/pasa2019

[GerMarsh]

Crikey! I never knew it was that powerful, especially for diverse farming!!

Thank you very much!

|Best regards,

Gerald Marsh (+44 (0)770 965 6697)| On 18/03/2019 13:23, Michael Stenta wrote:

@GerMarsh https://github.com/GerMarsh Feel free to screenshot some of the slides from the recent PASA workshop: https://farmier.github.io/pasa2019

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/farmOS/farmOS.org/issues/15#issuecomment-473907500, or mute the thread https://github.com/notifications/unsubscribe-auth/Ak5MAlSeTWP69qeN2VKsbUQNkd5LF7wCks5vX5M1gaJpZM4KX9__.

---

This email has been checked for viruses by AVG. https://www.avg.com

[mstenta]

Closing old issues - we created a CONTRIBUTING.md file in the farmOS repo: https://github.com/farmOS/farmOS/blob/7.x-1.x/CONTRIBUTING.md