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

• Filename: SECURITY.md
• (Article) Add a SECURITY.md file to your Azure Repos
• (Article) security.txt A proposed standard that allows websites to define security policies.
• (Article) "security-README", proposed standard for open source repos
• (Example) Gitlab's Security.Txt
• (Example) NodeJS Security Policy via Dedicated Tab (GitHub)
• Given the low stakes of this project, just redirect concerns regarding code to the primary project

Issue Templates

• Filename: .gitlab/issue_templates/
• What exists?
• What aspects are necessary?
• Kinds of issues?
• (Article) A collection of GitHub issue and pull request templates
• (Article) About issue and pull request templates
• (Article) Step-by-Step Guide to Creating Issue Templates in GitLab
• (Article) Gitlab's Description templates
• (Example) Gitlab's Issue Templates
• (Search) GitHub "pull-request-template"

Issue Tags

• (Example) GodotEngine Issue Labels
• (Example) GodotEngine Issue Labels
• Peter personally likes the use of meta-tags to address missing tags (but only when a platform supports ease of applying these tags - which gitlab does not appear to do)
• (Discussion) How to automatically set a label on each new issue at creation?
• Should probably reflect process of an issue
  • 1. Unassigned
    2. In-Progress
    3. Blocked
    4. Needs-Reviewing
    5. Merged
• 2022-02-13T00:29:00-04:00 Peter:
  • Created Three Types of Labels:
    • (These are prefixed onto each label)
    • Status: What stage of completion a task is in
    • Task: What the task activity is
    • Topic: What area of work an issue is applicable to
  • Created these labels:
    • Status: BLOCKED "URGENT - This issue is blocked and in need of assistance" Red
    • Status: FIXME "There are errors on this issue - either labels are missing, the task is ambiguous, or the issue has been left stagnant" Pink
    • Status: In Progress "This issue is actively being worked on" Bright-Green
    • Status: In Review "This issue has been assigned to someone for review" Yellow
    • Status: Moved "This issue has been moved into another issue - see Issue for details" Purple
    • Status: Resolved "This issue has been successfully closed" Blue
    • Status: Unassigned "This issue is in need of volunteers" Tan
    • Task: Bug "Something is incorrect and needs to be replaced or fixed"
    • Task: Improvement "Something needs new features, capabilities, or design"
    • Task: Proposal "This issue is proposing some new idea"
    • Topic: Class "Some requirement from the SE420 class"
    • Topic: Docs "Written specification for something is needed"
    • Topic: External "Some interaction with a third party is needed - emails, schedules, meetings"
    • Topic: Team "Organizing, Event Creation, Scheduling, HR, Management"
  • Created these boards:
    • Development:
      • Unassigned
      • In Progress
      • BLOCKED
      • In Review
      • Resolved
      • Moved
      • FIXME

Issue Management

• Milestones
• Boards
• Due Dates

Current Issues

• What things need to immediately get done/have a physical impact?

Misc

• Peter: Creating res/ folder for static objects
• (Example) NodeJS "Governance.Md"
• (Example) GodotEngine Bug Report Issues is intended more for immediate technical-issues
• (Example) GodotEngine Feature Enhancement Issues is intended more for extended-discussion
• (Example) GodotEngine developers tend to organize in an adhoc manner, primarily through text-chat
• (Article) Gitlab Badges
• GitLab does not support badges on private instances (the gitlab.cci.drexel.edu instance as example)
• Will just use regular badges as result

New Directory Structure

team-blue/:
  .gitlab/issue_templates/:
    bug-report.md
    class-assignment.md
    documentation.md
    external-interaction.md
    proposal.md
    team-process.md
  documents/:
    decisions/:
      0001-use-decisions-as-docs.md
    developers/:
      conduct.md # BIG how to be nice
      contributing.md # BIG contrib guidelines
      decisions.md # EXPLAIN how to make decisions
      processes.md # EXPLAIN labels, decision, how the project fits together
      discussion-template.md
      writing-changelogs.md
    discussions/:
      2022-02-12.md # a name might follow these as well
    public/:
      # anything the general public might need to see
      security.md # who to really contact
  resources/:
    team-logo.png
    drexel-logo.png
    cc-by-logo.png
  changelog.md
  credits.md
  license.md
  readme.md

Working Style

• Peter: For this repo (the team), branching style will probably be best style to use
• Peter: For the external project, an entirely new repo is probably most suitable