Select Git revision
2022-02-12.md
-
Peter Mangelsdorf authored
Removed 'documents' directory; merged resources into single 'resources' directory; moved 'special' documents to 'root-level'; NOTE RESOURCE LINKS BROKEN (needfix)
Peter Mangelsdorf authoredRemoved 'documents' directory; merged resources into single 'resources' directory; moved 'special' documents to 'root-level'; NOTE RESOURCE LINKS BROKEN (needfix)
2022-02-12.md 14.83 KiB
- 2022-02-12
- Big Idea
- Using this File and Directory and Editor and Language for Immediate Task Resolution
- Immediate Tasks
- README
- Content License
- Conduct
- Code Contributing Guidelines
- Arch Files
- Change Logs
- Security
- Issue Templates
- Issue Tags
- Issue Management
- Current Issues
- Misc
- New Directory Structure
- Working Style
2022-02-12
Big Idea
- There are a bunch of decisions that have to be made
-
- Where to put notes
-
- Microsoft / Teams / OneNote (WYSIWYG)
- Gitlab / Wiki (Markdown)
- Repo / Docs Directory (Markdown)
- Repo / Obsidian Directory (Modified Markdown)
- Repo / Code Directory (Markdown) (Place Notes alongside code) (Requires rigor regarding linking/dating of notes)
- Repo / Docs Directory (ReStructured Text) (More Popular with Python projects, better formatting/structural writing)
-
- Code of Conduct
-
- Contributing Guidelines
- Where are the discussions for this?
-
- Issue Templates
- What formats to use? What do people find useful?
-
- Which Platform to use (EvaP or Sakai)
- Need to ask Jeff Salvage about difficulty of maintaining adapters
-
- 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
-
- 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
-
- Purpose of Repository
- If direct contributions to EvaP/Sakai are intended, how to go about doing so?
-
- 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
- I have decided we will not be using any "
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
-
- Unassigned
- In-Progress
- Blocked
- Needs-Reviewing
- 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" RedStatus: FIXME
"There are errors on this issue - either labels are missing, the task is ambiguous, or the issue has been left stagnant" PinkStatus: In Progress
"This issue is actively being worked on" Bright-GreenStatus: In Review
"This issue has been assigned to someone for review" YellowStatus: Moved
"This issue has been moved into another issue - see Issue for details" PurpleStatus: Resolved
"This issue has been successfully closed" BlueStatus: Unassigned
"This issue is in need of volunteers" TanTask: 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
-
Development:
- Created Three Types of Labels:
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