Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: simplify contributing page #267

Open
5 tasks done
fyliu opened this issue Mar 5, 2024 · 5 comments · May be fixed by #395
Open
5 tasks done

docs: simplify contributing page #267

fyliu opened this issue Mar 5, 2024 · 5 comments · May be fixed by #395
Assignees
@fyliu
Labels
complexity: small All steps are laid out in detail so that someone new to the project can work on it documentation Improvements or additions to documentation feature: Onboarding/Contributing.md For issues involving our CONTRIBUTING.md role: dev lead s: PD team stakeholder: People Depot Team size: 2pt Can be done in 7-12 hours
Milestone
05. Team Workflow

Comments

@fyliu
Copy link
Member

fyliu commented Mar 5, 2024 •
edited
Loading

Overview

We need contributing docs more suitable for contributors of our project that should already know the basics. The main page should be kept simple with links to more detailed explanations. A short but useful contributor intro to the project will make it more accessible.

Action Items

  • Create a contributing folder in docs/ to hold contributing pages
  • Move most or all sections out of the contributing page into pages in contributing/
  • Split CONTRIBUTING.md from docs/contributing/index.md
    • Replace links to CONTRIBUTING.md with short description and link to contributing/index.md
    • Replace contributing/index.md sections with short descriptions and links to individual pages

Instructions

  • Keep the contributing page short but usable by experienced devs
  • Link to detailed pages for clarification
  • What this means is to expand the CONTRIBUTING.md file into a folder of contributing documents for everything related to PD development 
    contributing
├── index.md
├── team.md
├── dev_environment.md
├── issues.md
├── git.md
├── documentation.md
├── ...
├── how-to
│   ├── add-model-and-api-endpoints.md
│   └── ...
└── tools
    ├── docker.md
    └── ...
@fyliu fyliu added documentation Improvements or additions to documentation size: 5pt Can be done in 19-30 hours s: PD team stakeholder: People Depot Team role: dev lead feature: Onboarding/Contributing.md For issues involving our CONTRIBUTING.md labels Mar 5, 2024
@fyliu fyliu added this to the 5 - Team Workflow milestone Mar 5, 2024
@fyliu fyliu changed the title Improve contributing docs [docs] Improve contributing docs May 17, 2024
@fyliu fyliu changed the title [docs] Improve contributing docs [docs] simplify contributing docs Jun 3, 2024
@fyliu fyliu changed the title [docs] simplify contributing docs docs: simplify contributing docs Jun 10, 2024
@fyliu
Copy link
Member Author

fyliu commented Jun 14, 2024

Edited the issue description around the goal of simplifying the page. Removed text that should go into separate issues.

@fyliu fyliu changed the title docs: simplify contributing docs docs: simplify contributing page Jun 14, 2024
@fyliu fyliu self-assigned this Aug 13, 2024
@fyliu fyliu added complexity: small All steps are laid out in detail so that someone new to the project can work on it size: 2pt Can be done in 7-12 hours and removed complexity: x-large size: 5pt Can be done in 19-30 hours labels Aug 13, 2024
@fyliu
Copy link
Member Author

fyliu commented Aug 13, 2024

The complexity is small since it doesn't modify most of the contents of the newly created pages. That will be done in future issues.

@fyliu
Copy link
Member Author

fyliu commented Aug 22, 2024

Updated issue tasks to split CONTRIBUTING.md from contributing/index.md. The page used to just be a reference to CONTRIBUTING.md

The problem with this issue is it splits up CONTRIBUTING.md into smaller files, and any other PR changing CONTRIBUTING.md is going to get a massive conflict with it. I see PR #370 having one of those changes, so I will create this issue's PR when that's merged.

@fyliu
Copy link
Member Author

fyliu commented Sep 27, 2024

I need to create the PR from my changes. Need an hour's time.

I have the changes done but I was trying to figure out if there's a way to do the commits so it's easier for other people to merge changes from before my changes, because my change splits 1 file into 5-6 files. I tried it and the changes is about 100% of the files.

If I don't figure out a way with the git diff strategies, I'll just create the PR from what I have.

@fyliu
Copy link
Member Author

fyliu commented Oct 1, 2024

I created a guide for manually applying changes to a different files, so that if someone made changes to the old long CONTRIBUTING.md, they can manually but successfully apply those changes as patch files when merging. Link

@fyliu fyliu linked a pull request Oct 2, 2024 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@fyliu fyliu

Labels
complexity: small All steps are laid out in detail so that someone new to the project can work on it documentation Improvements or additions to documentation feature: Onboarding/Contributing.md For issues involving our CONTRIBUTING.md role: dev lead s: PD team stakeholder: People Depot Team size: 2pt Can be done in 7-12 hours
Projects
P: PD: Project Board
Status: 🏗In progress (actively working)
Milestone
05. Team Workflow
Development

Successfully merging a pull request may close this issue.

Simplify contributing fyliu/peopledepot
2 participants
@fyliu @ExperimentsInHonesty