[ENH] Add a CONTRIBUTING.md to signal to contributors that we are accepting contributions and how.

[markdav-is]

Oqtane Info

Version - all
Render Mode - any
Interactivity - any
Database - any

Describe the enhancement

The process for contributing fixes to issues makes assumptions about following "standard githib" modalities.
Let's codify the process so we can cut down on explanatory coms in the form of a CONTRIBUTING.md file.

Anything else?

[thabaum]

Oqtane Contribution Process - Addressing Mass Emails and Standardizing Contributions

The process for contributing to Oqtane, particularly in the documentation repository, could be improved to ensure that both contributors and maintainers have a smoother experience. One of the key pain points that many contributors, including myself, have encountered is the volume of emails generated from pull requests (PRs). This can be overwhelming for maintainers, particularly when contributions are small or frequent, and it can be discouraging for contributors who don’t want to inundate maintainers with notifications.

Key Points:

1. Email Flooding:
   When contributing via Visual Studio Code or the GitHub interface, it’s common for contributors to inadvertently trigger a large number of emails to maintainers, especially when there are multiple small changes or multiple contributors submitting PRs at once. This is especially true when maintainers like @sbwalker and @iJungleboy are frequently involved in reviewing and merging PRs.

2. Contributor Experience:
   Many new contributors may be hesitant to participate due to the fear of creating an excessive amount of notifications or making a mistake in their PRs. The process of contributing should be as accessible and flexible as possible, and contributors should not feel overwhelmed by the technicalities or worried about bothering maintainers.

3. Standardizing Contributions:
   We should establish a clear, documented process for contributing to the repository that allows flexibility for contributors with different experience levels while also minimizing unnecessary noise for maintainers. This could include:

   • **Creating a Contributing.md that outlines the preferred methods for creating PRs (e.g., using forks, branches, and submitting small, incremental changes).
   • Clarifying Multiple Methods: Since different contributors might prefer different workflows (Visual Studio Code, Visual Studio, GitHub Web Editor, or command-line Git), it’s important to outline the different ways to contribute and highlight the most efficient method for those who want a streamlined, "clean" process for larger contributions.
   • Email Management: Encourage maintainers to set up email filters or forwarding rules to manage the influx of PR notifications. For contributors, make it clear that they can use these same methods to manage notifications on their end.

4. Fostering More Contributions:
   The primary goal is to encourage more contributions to the project by lowering the barriers to entry. We should not assume that all contributors have the same technical knowledge or experience with GitHub workflows. Providing clear instructions for simple contributions—such as how to submit a small fix directly via the GitHub interface—will help a wider range of people contribute.

5. Documentation:
   This is where a well-structured documentation effort, including a comprehensive contributor guide, will make a big difference. We need to clarify:

   • How to submit a PR.
   • How to avoid triggering excessive notifications.
   • The expected workflows, both for minor and more serious contributors.
   • The process for large documentation changes (such as PRs that add significant updates or new sections to the docs).

6. Next Steps:
   As suggested, the best next step would be to create a dedicated section in the documentation that explains this process clearly. This will help potential contributors feel more comfortable and avoid any unnecessary confusion. I also recommend linking this section directly from the main Oqtane Docs repository, ensuring contributors can quickly find and reference it once it has been created.

I would like to see more open source projects for Oqtane Framework be created for the Marketplace is my goal as I know there are people hungry for them. Keeping helpful information limited to just those that have been working with open source projects regularly will limit Oqtane's growth. I believe my vision of what I would like to see in documentation will be to assist an even larger base of not only contributors, but future marketplace Oqtane extension providers., both open source and commercial.

Additionally, I agree that maintaining a balance between convenience for contributors and minimizing overhead for maintainers is essential. We don’t want to discourage contributions because contributors feel that their efforts are too small to be worth a large, disruptive process. The more we can streamline the contribution process, the more likely contributors will feel comfortable participating.

For further context, I’ve raised a similar issue in the Oqtane Docs repository regarding these concerns:

• Oqtane.Docs Issue #87: This enhancement request will outline the challenges I’ve faced, including the mass email problem and some of the suggestions for improvement for an acceptable workflow and how it is unrealistic to expect developers to know how to contribute while working with GitHub easily.
• Additionally, Oqtane.Docs Issue #3 was created in 2021 and includes a discussion about contributing to the Oqtane Docs repository for the database schema.
• Recent PR: I’ve also submitted a recent PR that highlights some of the challenges with the contribution process and provides updates for Oqtane 6.0.0, including the database schema.

Maybe this was a bit much for anyone to digest, it is easier to focus on work at hand I get it. I have to admit being discouraged A LOT during all my past processes getting pull requests merged into both projects in the past and recently.

I really would love to just throw the towel ;) but here I am posting a long post again... who will even read this :)

Thank you.

[sbwalker]

@thabaum "email flooding" his not really an issue in the main oqtane.framework repo. The oqtane.framework repo has over 2600 PRs at this point and in general there is only a single email notification sent when a PR is submitted. The only exception to this case is when additional commits are added to the original pull request - which is generally something which should be avoided (ie. a pull request should be submitted when a feature is deemed to be "complete" as then it is clear to everyone that it is ready for review/merge).

I definitely think it is a good idea (and open source best practice) to have a Contributing.md file to make the contribution process clearer and easier to follow.

[sbwalker]

@thabaum in regards to the Docs repo... there was discussion back in Jan/Feb about this topic. A number of people indicated that they believed the existing tooling is a barrier to entry for contributing to the documentation. An alternative option was proposed to use the content management capabilities of Oqtane to maintain the documentation. I even created an initial Wiki module for this purpose (https://github.com/oqtane/oqtane.wikis). However, at this same time a Documentation Team organically formed within the community and decided that it would prefer to use the existing tooling. So that is why we never moved forward with an alternate approach. We will likely need a different contributing.md for the Docs repo than what is needed for the oqtane.framework repo, as the tooling requirements and process are different.

[thabaum]

@sbwalkerCertainly! To clarify and add my 2 cents to these talking points below:

(ie. a pull request should be submitted when a feature is deemed to be "complete" as then it is clear to everyone that it is ready for review/merge).

In a perfect world with perfect contributors and perfect humans (maybe even with brain implants to produce flawless code and docs), this would be true. But I’m only human. Often, I’ll produce something for docs and, after I felt it was 100% complete, I’ll notice a few things that aren't quite right. This happens nearly every time. I enjoy making mistakes—it’s a reminder that I’m human. If I can catch those mistakes before something is merged, then that’s great.

For documentation, I’m told to push things even if they’re 80% done, and as for commits, why would any maintainer care if someone takes time to fix more issues or adds more fixes to other problems within the same PR? If we’re encouraged to make ONE big PR for all of them, then why is there a push to break things down into smaller PRs here? In this repo, it’s not the case that we’re working on everything in one large PR; you prefer them to be broken down. But why? Why is it that, at the same time we’re talking about needing more contributors, we’re being so picky about how those contributions are made?

From a newcomer’s perspective, it’s not very inviting to read through these conversations and see how contributors are treated when they’re just trying to help. It doesn’t foster a welcoming atmosphere.

There was discussion back in Jan/Feb about this topic. A number of people indicated that they believed the existing tooling is a barrier to entry for contributing to the documentation. An alternative option was proposed to use the content management capabilities of Oqtane to maintain the documentation. I even created an initial Wiki module for this purpose (https://github.com/oqtane/oqtane.wikis).

My suggestion was to create a Learn.Oqtane.Org website. Others suggested building a wiki. I said, “Why not build both?” Create a central "learn" page that gathers all these contributions in one place and makes it accessible to everyone who wants to help. I also said that I would help with the documentation because I felt this was a critical source that others could contribute to as well.

At this point, I’ve been focused on making the Oqtane Docs as much of a “Learn Center” as possible—something that has always been the intent. This isn’t that hard to do; it’s similar to creating a Contributing.md file, in fact, it’s almost the same thing. What’s the big deal?

As for the Wiki, while it was promoted by others, I wasn’t as enthusiastic about it. It seemed like adding yet another layer to a project that, frankly, we as a community don’t fully support. Has anyone even contributed to the Wiki? It was pushed for, but then nothing happened.

There’s only so much of me to go around. I chose to focus on documentation because there was already someone willing to organize meetings and keep that project moving forward. If there were others actively contributing to the Wiki, I’d gladly help. But the reality is, it’s still not moving forward. If we really want a vibrant documentation ecosystem with multiple contributors, we need active participation.

If anyone who supported the Wiki effort steps up, I’ll gladly help make the Oqtane Learn Center a richer and more valuable resource. We need more contributors to keep the documentation growing.

I’m organizing all the places where someone can easily click the "Edit" button and add their own resource to share. It’s the same idea as editing the Readme.md file in this repo—easy for anyone to contribute to, almost like creating a GitHub issue.

Once my next PR in Docs gets merged (hopefully), it will add video links to all the recently found sources in the guides section. This will provide a clean and accessible way for others to contribute their resources too. It’s an ongoing effort to make the documentation more community-driven and inclusive. More to come...

"I have been waiting to create a Wiki link, but there is no Wiki yet for anyone to contribute to, is there? oqtane.org/wiki?"

I’m heavily invested in the Documentation team, where I’m the leading contributor, and I’d love to see the Contributing.md file created here soon. I look forward to its creation because it will help establish clearer guidelines for contributing.

I don’t think anyone should have hard feelings about this. It’s all about collaboration between contributors and project maintainers. I don’t personally gain much from this—I don’t need docs as much as others might—but I want to see more people participating in developer and doc meetings. We’ve had the same few people in those meetings since they started, and I want to change that.

A more "lax" environment would be more welcoming, in my opinion. At the same time, if we want things done in a certain way, we need clear directions. PRs can be handled in different ways, so having that clarity is crucial.

"Here’s a scenario:
A college student needs an open source project to contribute to. Is Oqtane going to be a friendly choice for them to be a part of? Or will they feel like they might do something wrong, receive extra emails, and end up fixing a PR they submitted, hoping it gets reviewed when the maintainer finally has time? Do they just leave it broken after they catch something?"

Honestly, I feel like this is a direct attack on me, as I’m the only one contributing in a way that doesn’t strictly follow all the rules. But if I were that college student, I’d probably move on to another project where contributors are valued more for their input and less for how they follow a specific process. Is that what we want for Oqtane? A community where contributors feel like they’re walking on eggshells?

In my previous experience with DNN, I never had this issue. I was welcomed and encouraged to contribute, even if I wasn’t following every little guideline to the letter. It felt more collaborative. The maintainers were happy to see contributions, and they worked with me to help me improve my submissions, rather than nitpicking every small detail.

Every project is different, and this experience has given me insight into what someone who’s not getting paid to contribute might feel. Personally, I value the experience of working with all of you. That’s what I get out of it.

But Oqtane is supposed to be a project to learn from as much as it is one to build upon.

Cheers!

🍻

[sbwalker]

@thabaum the requirement for "small pull requests" in this repo is not just a personal preference of my own, it is actually an industry best practice when using Git. You can Google "pull request best practices" and you will find plenty of articles which mention this approach ie:

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests
https://www.atlassian.com/blog/git/written-unwritten-guide-pull-requests
https://athenian.com/blog/why-pull-request-size-matters

In regards to the Wiki topic, it was never deployed for a couple of reasons: 1) there was concern raised that there were already too many different locations for Oqtane documentation (ie. docs, blog, etc...) so it seemed that the general consensus was to concentrate efforts on one area rather than many, and 2) the Documentation team made a decision to use the existing tooling -which is a proven approach and works well once the technical aspects of the process are understood.

@thabaum your contributions, and the contributions of every other member of the Oqtane community, are valued. The important thing to understand is that there are always 2 sides to contributions - there is the submission, and there is the review. In order to manage contributions effectively there is tooling and best practices to streamline the process. This is true for all large-scale software development projects - not just open source projects. The only difference is that in open source, the contributors and reviewers are generally not paid for their efforts - they are volunteers who are participating for the greater good of the community.

The comments about your recent contributions to the Docs repo generating 100's of email notifications was not intended to be an "attack" om you personally. It was intended to let you know that whatever process you were following was producing different results than what you were probably expecting. Its not uncommon that when you try something new that there are unexpected side effects - and its usually appreciated when others make you aware of those side effects so that you can manage expectations.

[markdav-is]

I'm going to make a basic CONTRIBUTING.md in a feature branch as a starting point. The guidance I'm following can be found here: https://mozilla.github.io/open-leadership-training-series/articles/building-communities-of-contributors/write-contributor-guidelines/

The main points are:

• we track issues in github
• issues are pseudo-tagged with [BUG], [ENH], more.
• we are accepting PRs
• we use the github flow process

this is more of a checklist and less of a how-to. Having this will be a signal to potential contributors that we are open to contribution and the basic flow.

[markdav-is]

I've started a branch for this here: https://github.com/Trifoia/oqtane.framework/tree/4803-Add-a-CONTRIBUTING.md

[markdav-is]

PR submitted #4837

[thabaum]

@sbwalker totally agree with all you said and fully understand. Consider what I presented feedback and an experience that I would blame Github/Microsoft for as you can create a single commit using "Git" but using the tool extensions for codespaces and VS Code it pumps out every change you made as a commit/email with a PR instead of just one email for the entire PR.

I really did have a bit of a chuckle with it pushing out so many changes as I did a lot of work. Codespaces tracked all these changes, but if I would have used git I don't think all the changes would of been in many commit emails, but a single one. I would have to explore this more as it was nice to use, but it was very confusing and I could not tell what I was stashing/commiting/pushing 100% in order to keep up with other PR's and commits made to the project repository. On a large PR with 50 pages or whatever... a lot of artifacts got included in the PR's such as stash comments I had to remove... which made more commits/emails.

I expected maybe 1 email for the PR and then a maintainer can review the commits of that PR. Using git to create the commit instead makes all those commits into 1 commit/email I believe which has been best practice as this did change the number of commits showing up. Also using the web interface created a commit each time you save a page... if the initial PR has not been made yet, this is OK I believe, but after the PR was made and you want to update a few pages there will be a few commits/emails... On the bright side, I now know 6 ways to Sunday how to create PR's and commits for a project.

As for industry best practices... Oqtane.Docs adheres to no such practices as I am told to submit even docs 80% done. This was due to the fact things are very behind on that project. This PR submitted really caught us up i that area. There is a huge overhaul of the docs which I submitted not knowing if it would even be accepted, without any real discussions just putting up an idea after trying to update the manuals. It was accepted and I pushed another couple after our meeting which really was me testing out all the ways to contribute to GitHub open source projects to find the one solution that is going to work best for documenting how to contribute, for contributors providing commits in different PR cases.

Oqtane.Docs is now down to just a handful of issues (all but one I created) and I am hoping with my experience I can create a helpful contribution page contributors can simply follow a basic set of instructions to help keep documentation enhanced and current I will try to provide to encourage growth in contributions in that project.

As for the Wiki, I feel it would be a great place for those who like to contribute information in this way, but again like said it does create more to maintain in order to keep current. We would need a way to log into the wiki to provide information and it would need approval processes I am guessing so that it would not get abused... seems like a lot of overhead but could be worth it if it was properly handled.

I still like the idea of a learn.oqtane.org website page that links all of these sources, including video channels on YouTube. But again, that site would need a maintainer as well and we are spread thin as is. I just wanted to make a basic page that points them in all the main directions to for Oqtane help and support. I can see this being the "Hub" for Oqtane developer information.

I am working on this more or less as a POC as part of the Oqtane.Docs "Guides" sections to shine light on things I didn't even know existed. Things like sources of videos I may need to reference back to and check for updated content and material to review. Maybe we can have a thread here where people can post a link to get their video channels/Blogs included on that site and once a month or three... update that site when time permits from the links that prove to be valid still and are submitted as requests to link others to these online resources. Just some ideas as whatever we do it needs to be super simple to maintain and make sense for anyone involved.

I made a huge contribution over the last month on Docs, I will try to do it one more time after the next Oqtane Docs Meeting next week prior to the Oqtane Developer Meeting. I am going to try to purge all the issues by then so it is no longer considered a WIP. Oqtane is too mature of a product to have a WIP docs IMO. So with @iJungleboy help and anyone else that can push the agenda Oqtane.Docs is pretty much Oqtane Learn going forward.

I put a lot more time than I thought I would into that huge PR that blew up the email systems. Once I get started on something I want to finish it the best I can. One thing led to another and I just kept going until it felt 100% worthy of allowing everyone to review. I hope there are at least a couple issues created now and again for any problems with our current docs pages going forward so we can fix things as needed if not a great place for a first time GitHub contributor to work out submitting a fix on a typo or information that needs updated.

The new layout should be a lot more self explaining on where things go and how to find what you need. There will always be room for improvments as a lot of it is just something to get each section started.

A guide for contributions is on deck again after we can discuss things further at the next meeting I am hoping. I burnt a lot of my "spare" time I really didn't have on that last contribution and need to catch up here in this repo more with Oqtane 6.0 and .NET 9.

I like keeping things industry best practices here and for the most part I believe I have. As for the docs project keeping it a little looser at least until it gets past the WIP stage.

Thank you @markdav-is for creating a PR, when I have time I will review it and enhance it in our documentation as well.

Cheers!

🍻