Fix #194, Create Contributing.md

[ArielSAdamsNASA]

Describe the contribution
Fix #194
The Contributing.md file contains a table of contents and instructions on how to report bugs, request features, view security vulnerabilities, create pull requests, participate in discussions and ask questions, and how to write high-quality code.

Additional context
I would like to collaborate as a team on this file. Please review my main concerns and questions. Feedback is appreciated.
Code of Conduct example: https://www.contributor-covenant.org/version/1/4/code-of-conduct/

Main Concerns/Questions

1. I would like to finish the section "Writing High-Quality Code". It was written by @CDKnightNASA and @astrogeco. Thoughts/feedback on how it should look like?
2. What format do we want to use for commit message convention and PR convention. There are three different formats that were used throughout our documentation.

• Fix-ISSUE_NUMBER-<FIX_SUMMARY>
• Fix ISSUE_NUMBER, 50-ish-character-long summary of commit content
• Fix #XYZ, SHORT_DESCRIPTION

3. Do we want to enforce a name convention for branches? I haven't seen developers using this.

Create a new branch in your fork to work on your fix. Please name your branch fix-ISSUE_NUMBER-<FIX_SUMMARY>.

4. For the Discussions and Questions section, it would be great to explore how cFS can allow for more discussions from the community. Some ideas include using gitter.im, discourse, or a discussions template to submit in the issues along with an appropriate label. Thoughts/feedback?
5. I would also like to work together to create a code of conduct before publishing this document. Thoughts on what it should look like?

Contributor Info - All information REQUIRED for consideration of pull request
Ariel Adams, ASRC Federal

[astrogeco]

I can't remember if we have this but another thing is, for now, to ensure that we have our "real names" associated with the github profile

[ArielSAdamsNASA]

Updates:

• Updated Discussions and Questions so users do not submit GitHub issues, instead they should email us.
• Update name convention for branches to recommend the convention rather than enforce it.
• Ensure that we have our "real names" associated with the GitHub profile

[skliper]

Is there really a problem with user's submitting questions as issues? We have the "question" category, and it's more publicly available than the community email list (some international users are unable to register to the community email list). When/if we ever do get a real Q&A/FAQ system it may be easier to transfer issues over that are clearly marked than it would be to review all the community emails to prune useful correspondence... Also issues benefit from a clear thread and resolution marking, whereas community emails are much more freeform (not always clear when a question as been completely answered, often spawn multiple discussions).

[ArielSAdamsNASA]

@skliper I do not like users having to email us questions either. My issue with opening a question on GitHub is that most expert users do not check the issue tracker as often as developers. When asking a question on the issue tracker, developers will reply to it even if other users can reply to it. So, asking questions on issue tracker not only robs maintainers’ time but also robs chance of growing user community too. I noticed in the most recent question on the cFE repo was only answered by you, Jake, but when asking the same question through our email David Jobe, Johnathan Wilmot, and Allen Brown answered the question. I prefer using a real Q&A system and forum as soon as possible. I mean we already have a core-flight-system tag on Stack Overflow. If we continue using GitHub for questions, I do want to provide a questions template as others have suggested.

We have the "question" category, and it's more publicly available than the community email list (some international users are unable to register to the community email list).

Are international users not able to email the community email list either?

[skliper]

@ArielSAdamsNASA - all good points, but sound more like process/resource issues than platform issues. If someone was responsible for community interaction at a cFS management level perhaps they could manage a coordinated, high quality, official response in a much more effective manner?

Just a caution - stack-overflow is not always as "friendly" an environment as I'd prefer we promote for our stakeholders/customers.

[ArielSAdamsNASA]

@astrogeco Thoughts or comments?

[zanzaben]

I agree that going through github causes a lot of non-developers to never see them and that we should be trying to grow more community engagement. A dedicated forum would be best but using the email list in the short term is better than github in my opinion.

[astrogeco]

All valid points. I think it is more than just resources or process. The platform and its reach matters. I think having a community and engagement team or making that job explicitly part of our metrics as a program in some way is the right way to go. Like @zanzaben said the email list, though imperfect, is better than github for this at the moment.

Receiving questions in the mailing list gets people excited and creates an opportunity for people to connect which is what we want.

I agree with the stackoverflow perspective, I have seen some harsh interactions and behavior that does not align with where we want to go as a community

[astrogeco]

Maybe we should move this up so people see it earlier. Also we should distinguish between q&a community type things which should go to https://lists.nasa.gov/mailman/listinfo/cfs-community versus programmatic questions like requests for information, partnerships, training, etc.

[ArielSAdamsNASA]

Moved Discussions and Questions as the first section of Ways to Contribute.

[skliper]

Like @zanzaben said the email list, though imperfect, is better than github for this at the moment.

While certainly a fair opinion from a specific perspective, I'd recommend objective criteria for determining "better".

The email list does not support the entire community that has access to GitHub. I consider this a deal-breaker for relying solely on the email list or directing all queries to this platform, since that basically disqualifies a subset of our community from interacting or reaching out with questions. Do we really want to promote this exclusivity?

We continue to all agree GitHub isn't perfect either, but it does provide "threads", "labels", easy searches, has the same reach as the code, can be curated, etc. The email list also has downsides in that it's hard to tell what the "official" response is, searching is difficult, I'm not aware of a way to remove bad answers or out of scope issues, etc. On either platform it's easy to manage/solicit responses from specific people. Although the reach of the email list is in the 200-300's, GitHub and it's entire issue history has a much wider reach regardless of a "subscription" that may or may not even work for the user.

[skliper]

Another benefit of a "public" platform such as GitHub is search engine coverage. The only way to search the email list is first off knowing where that search interface is, being a member, and using the antiquated interface.

[zanzaben]

While certainly a fair opinion from a specific perspective, I'd recommend objective criteria for determining "better".

The main objective is getting as many people as possible to interact with each other. People aren't currently doing that over Github, they are doing it over email.

All the other benefits you listed for github don't matter if no one is there to use them. Which is why in the short term using the system that people are currently using is the best option because getting people to move from one platform to another is an incredibly hard thing to do that gets exponentially harder the more times you do it so we shouldn't try to move them to github when we all agree it isn't a good long term option.

[astrogeco]

How about this for a compromise, let's make a "question" issue template that encourages the author to send the question by email to the community. I'm sure we could even find a workflow or a github bot that does the forwarding for us.

[astrogeco]

Another point to consider, and that I don't like, is that some companies might actually prevent their employees from posting to github as an open forum but are more lenient with the "closed" mailing list. How might we address this challenge?

[skliper]

I think we are agreeing neither the email list or GitHub individually address every issue. It's for that reason I'm trying to advocate for continuing to allow questions to be submitted on GitHub. Sure, you get a different crowd, but saying you can only submit issues on the email list cuts out a portion of the community's capability to even ask the question.

[astrogeco]

Let's continue the community conversation in #207

[ArielSAdamsNASA]

Updates:

• Removed the section Writing High Quality Code
• Moved Discussions and Questions to the top of the Ways to Contribute
• Add that users can submit questions to GitHub or email us. Add subscription information
• Add code of conduct. Used standard template from https://www.contributor-covenant.org/version/1/4/code-of-conduct/

[zanzaben]

I think we are agreeing neither the email list or GitHub individually address every issue. It's for that reason I'm trying to advocate for continuing to allow questions to be submitted on GitHub. Sure, you get a different crowd, but saying you can only submit issues on the email list cuts out a portion of the community's capability to even ask the question.

I think it's good to leave both as options for this pull request.

[astrogeco]

@ArielSAdamsNASA do you want to ammend the commit so it shows you as author and me and Chris as coauthors?

[ArielSAdamsNASA]

@ArielSAdamsNASA do you want to ammend the commit so it shows you as author and me and Chris as coauthors?

Updated the commit.