2022-02-12.md

2022-02-12

Big Idea

• There are a bunch of decisions that have to be made
• 1. Where to put notes
  • 1. Microsoft / Teams / OneNote (WYSIWYG)
    2. Gitlab / Wiki (Markdown)
    3. Repo / Docs Directory (Markdown)
    4. Repo / Obsidian Directory (Modified Markdown)
    5. Repo / Code Directory (Markdown) (Place Notes alongside code) (Requires rigor regarding linking/dating of notes)
    6. Repo / Docs Directory (ReStructured Text) (More Popular with Python projects, better formatting/structural writing)
• 2. Code of Conduct
• 3. Contributing Guidelines
  • Where are the discussions for this?
• 4. Issue Templates
  • What formats to use? What do people find useful?
• 5. Which Platform to use (EvaP or Sakai)
  • Need to ask Jeff Salvage about difficulty of maintaining adapters
• 6. How to Merge Notes
  • Already scattered all over the damn place
  • Need to merge - how?
  • • SE420 FA22Q2 Teams OneNote Notebook (This will probably continue to see use, especially regarding sensitive information)
    • Peter's Google Keep (In Progress Download and Transfer) (No Longer Relevant/Needed)
    • Peter's Personal Notes (In Progress Transfer) (No Longer Relevant/Needed)
    • Also bear in mind use of Discord as a "temporary notes platform"
  • Eh, for now, not of concern
• 7. Required Qualities of Notes
  • What do people find useful/necessary?
  • Ability to simultaneously edit notes online at same time has been very popular recently
  • Thus promoting the use of in-browser microsoft word
  • Also note pattern of only one person taking notes
• 8. Purpose of Repository
  • If direct contributions to EvaP/Sakai are intended, how to go about doing so?
• 9. Who are the Notes for
  • External/Public? Put in docs/ directory (and not notes)
  • (Example) Gitlab Docs Folder

Using this File and Directory and Editor and Language for Immediate Task Resolution

• File: 2022-02-12.md
• Directory: team-blue/notes/
• Editor: Visual-Studio-Code
• Language: Standard-Markdown

Immediate Tasks

• About (README) (Needs Fixes)
• License (LICENSE) (Needs Non-Code (Content) Section)
• Code of Conduct (CONDUCT)
• Contributing Guidelines (CONTRIB)
• Architecture (ARCH)
• Changes (CHANGELOG)
• Security (SECURITY)
• Issue Templates (.gitlab)
• Issue Tags
• Issue Management (boards) (milestones) (notifications)
• Current Issues (6) (On Tracker) (Assigned) (Deadlined)

README

• Filename: README.md
• (Example) Best-README-Template is what Peter likes to use on most projects
• (Article) Awesome README can also be useful

Content License

• Filename: LICENSE.md
• Such as Creative-Commons
• Peter: Using CC BY 4.0 (Almost as permissive as CC0 (Public Domain), just requires attribution)
• (Resource) Creative Commons Logos
• (Resource) Creative Commons Markdown
• (Discussion) Should I call my license file LICENSE, LICENSE.md, or LICENSE.txt? [closed]
• (Discussion) Does it matter what I name my open source license file? [closed]

Conduct

• Filename: CONDUCT.md
• (Example) Gitlab's Massive Handbook
• (Article) Contributor Covenant
• (Article) 18 of the Best Code of Conduct Examples
• (Search) "code-of-conduct-template" on GitHub
• (Article) Awesome Code of Conduct
• (Article) Your Code of Conduct
• Peter: From what I can tell, most organizations on GitHub or Gitlab write one or the other:
  • Really really basic codes of conduct (just copying the "contributors' covenant")
  • Really, really big codes of conduct (which they then host on their own website)
• Peter: I don't like just copying a code of conduct, and I especially dislike dealing with humans, so I am hesitant about just grabbing the contributors' covenant
  • Eh, whatever...

Code Contributing Guidelines

• Filename: CONTRIB.md
• What exists?
• What aspects are necessary?
• Google "what are code contributing guidelines"
• (Example) Contributing to Python
• (Example) Gitlab's "Individual contributor license agreement"
• (Example) Gitlab's "Process.Md"
• (Example) Godot Engine's "Contributing.Md"
• (Example) Lightning Network Developers' Code Contribution Guidelines
• (Example) DSpace Software's Code Contribution Guidelines
• (Example) Google Tensorflow's Contributing guidelines
• (Example) Microsoft's Mixed Reality Toolkit Coding Guidelines (Peter's personal favorite)
• (Example) Atom Editor's Contributing Guidelines

Arch Files

• Filename: ARCH.md
• (Example) Diem's "Implementation Details"
• (Example) Dependabot's "Architecture"
• (Example) Caddy's "Architecture"
• (Article)
• (Discussion)
• (Example) Rust Analyzer's "Architecture"
• (Article) From Architectural Decisions to Design Decisions
• (Article) Markdown Architectural Decision Records
• 2022-02-13T01:04:00-04:00 Peter:
  • I have decided we will not be using any "ARCH.md" files as we will be contributing directly to someone else's project
  • As such, I will put more of an emphasis on team decisions and meetings

Change Logs

• Filename: CHANGELOG.md
• (Article) Keep a Changelog is very popular
  • "Added", "Fixed", "Changed", "Removed" with bullet-lists linked to issues
• Often used with "Semantic Versioning 2.0.0" and ISO 8601 DateTime Strings
• (Example) Gitlab Changelog

Security