search

hackforla / peopledepot

A project to setup a datastore for people and projects at HackforLA. The link below takes you to the code documentation
https://hackforla.github.io/peopledepot/
GNU General Public License v2.0
7 stars 26 forks source link

Epic: collect needed documentation #378

Open fyliu opened 2 months ago

fyliu commented 2 months ago

Overview

This issue tracks the documentation that needs to be added and the issue/pr where they would've been helpful in. The intention is to make it easy to note any missing documentation without having to create the issue at the same time.

Action Items

Resources/Instructions

How to use

  1. Add a new comment for each documentation item needed using a copy of this template

    ### What's needed

- Description of what the missing documentation is about

### Draft (if written)

- Link to external docs with instructions (if applicable)

### Where it's useful

- Link to what prompted the need for this change/addition (if applicable)
- Situation where this could be used

### Where to put this

**contributing docs** should go in the `/docs/contributing/` folder or sub-folders:
- **how to guides** --> `/docs/contributing/howto/`
- **tutorials** --> `/docs/contributing/tutorial/`

### Audience

- Who or what role needs to perform this action

### Tags

- git, django, etc.

  2. Add an action item here, linking to the comment below

  3. Create an issue to add the documentation (can be done later by another person)

    • Then, hide the original comment and add the new issue # to the action item

  4. Work on the documentation issue and check off the action item (can be done later by yet another person)

fyliu commented 2 months ago

This comment has been moved to this issue/comment:

Common things to look for in a PR review

Where it's useful

Notes

It already exists here https://github.com/hackforla/website/wiki/How-to-review-pull-requests

fyliu commented 2 months ago

This comment has been moved to this issue/comment

Django: How to combine migrations

Say max_migration.txt is at 0027_... and you want to combine 0025-0027 into one.

  1. Roll back core app migrations to 0024

    ./script/migrate.sh core 0024

  2. Delete unwanted migration files

    rm app/core/migrations/00{25,26,27}_*

  3. Recreate max_migration.txt for core app

    docker-compose exec web python manage.py create_max_migration_files --recreate core
# the file core/max_migration.txt should contain "0024_..."

  4. Create combined migration file for core app

    ./script/migrate.sh core

Where it's useful

fyliu commented 2 months ago

This comment has been moved to this issue/comment

How to quickly checkout a PR

Setup: add this git alias to your global git config

[alias]
    pr = !sh -c \"git fetch upstream pull/${1}/head:pr/${1} && git switch pr/${1}\"

Usage:

To check out PR #383 to a local branch called pr/383, run this.

git pr 383

Notes:

Where it's useful

Extra info

I have another longer alias for checking out a PR to a pr/xxxx branch plus tracks the remote branch which created the PR. Here's the alias:

[alias]
    prt = "!f() { \
      git fetch upstream pull/${1}/head; \
      commit_hash=$(git rev-parse FETCH_HEAD); \
      remote_branch=$(git branch -r --contains $commit_hash | head -n 1); \
      git switch -C prt/${1} $commit_hash; \
      git branch -u $remote_branch prt/${1}; \
    }; f"

Usage:

git prt 383

Note:

fyliu commented 2 months ago

This comment has been moved to this issue/comment

What's needed

How to add git alias to the global git config

  1. Run this in the terminal to open an editor to to edit the global git config file.

    git config --global -e

  2. Add the git alias under the [alias] section and save the file.

  3. The alias is now available for use.

Where it's useful

fyliu commented 2 months ago

This comment has been moved to this issue/comment

What's needed

How to resolve migration conflict

Let's say you're rebasing and the max_migration.txt file shows a conflict. That's a sign that the numbered migration files are conflicting as well. They're named differently so their conflicts don't show up in git.

In many cases, you can resolve it using the rebase_migration command provided by django-linear-migrations.

  1. Let's say you rebase your branch to main and see a conflict in core/migrations/max_migration.txt

    git rebase upstream/main

    For this example, let's say the conflict shows that core/0025 and core/0027 are in conflict.

  2. Undo the rebase

    You'd have migrations applied that are part of the conflict. You need to roll the database back to a point before that, so you can change those migrations if necessary.

    git rebase --abort

  3. Roll back the local database to a previous migration (any number before the ones in conflict)

    ./scripts/migrate.sh core 0024

  4. Re-run the rebase

    git rebase upstream/main
# see conflicts returned

  5. Resolve the migration conflict

    docker-compose exec web python manage.py rebase_migration core

  6. Resolve any code conflicts

  7. Run all the migrations

    ./scripts/migrate.sh core

  8. Run pre-commit checks

    pre-commit run —all-files

  9. Stage all the fixes

    git add <max_migration.txt> <changed migration files> <fixed code files>

  10. Continue rebase

    git rebase --continue

Where it's useful

fyliu commented 1 month ago

This comment has been moved to this issue/comment

What's needed

How to apply changes from one file to a different file

Draft (unfinished)

Say we have a branch that contains changes to CONTRIBUTING.md and that the content being changed was moved to another file: docs/contributing/dev_environment.md. We want to manually apply our change to the file ourselves.

  1. Rebase/Merge your feature branch to main

  2. Undo changes to CONTRIBUTING.md

git reset upstream/main -- CONTRIBUTING.md
  1. Switch to our unmerged branch with the changes
git switch our-branch-original
  1. Create a patch of the changes
git format-patch hackforla/main CONTRIBUTING.md
# only changes to CONTRIBUTING.md
# include changes since we branched off from hackforla/main
# may need to create a temporary branch where hackforla/main used to be for this command

# output:
# 0001-add-to-dev-environment.patch
  1. Switch to rebased branch without the CONTRIBUTING.md changes
git switch our-branch-rebased
  1. Apply the patch to the new file
patch -p1 docs/contributing/dev_environment.md 0001-add-to-dev-environment.patch

Where it's useful

Audience

Tags

shmonks commented 1 month ago
shmonks commented 1 month ago
shmonks commented 1 month ago

Please provide update

  1. Progress: First issue created (for PR review guide) - will now adapt for the rest
  2. Blockers:
  3. Availability: Weekend
  4. ETA: Next week
ExperimentsInHonesty commented 1 month ago

@shmonks Please provide update

  1. Progress: All issues created - will now work with Vanessa to create a new issue template for any missing documentation
  2. Blockers: I need Fang to read through the new issues, and let me know whether I've correctly described the processes he wanted documented in each. The issues are listed in this comment: https://github.com/hackforla/peopledepot/issues/378#issuecomment-2435459046
  3. Availability: Next Tuesday now
  4. ETA: Next week
ExperimentsInHonesty commented 1 month ago

@shmonks If you create a template with placeholders[REPLACE WITH...] then you can get together with Vanessa, and show her how to create the issues using the template. Then she can write instructions for future documentation needs that come up.

shmonks commented 1 month ago

This epic has now been replaced by the following issues:

shmonks commented 3 weeks ago

Please provide update

  1. Progress: Done - except that I'm now thinking about creating a new issue template specifically for missing documentation issues
  2. Blockers: Is that wise?
  3. Availability: Friday pm, Tuesday
  4. ETA: Next week
  5. Pictures or links* (if necessary): "Add any pictures or links that will help illustrate what you are working on."
shmonks commented 3 weeks ago

Fang agreed that a new issue template for missing documentation would be good - so I'll proceed...

fyliu commented 2 weeks ago

What's needed

How to combine the last several commits into one.

This is not the only way but it's a fast way to achieve the goal.

  1. Assume we're at the head of the PR branch with 4 commits and want to combine the 4 commits into one.
  2. Soft reset to the earliest commit, with all the changes of the later commits staged. 
    git reset --soft Head~3
  3. Amend the staged changed into the earliest commit. 
    git commit --amend --no-edit

    note: omit the --no-edit flag if you want to edit the commit message.

There are alternative ways like lazygit and the standard interactive rebase. These are more interactive and more difficult to write out in text form.

Where it's useful

Audience

Tags

shmonks commented 2 weeks ago

Please provide update

  1. Progress: Fang's latest comment still needs to be made into an issue of its own.
  2. Blockers: I'm wondering about the status of this epic, which might be better converted into a conversation? Or an ER? I'm guessing Fang would like to use it as a notepad for recording missing documentation issues?
  3. Availability:
  4. ETA:
  5. Pictures or links* (if necessary):
ExperimentsInHonesty commented 2 weeks ago 
- <!-- Where in mkdocs it should go.  Provide url or indicate new page and parent page -->
fyliu commented 5 days ago

The contributing docs should go inside the /docs/contributing/ folder or sub-folders

maybe temporary locations

fyliu commented 4 days ago

What's needed

A guide for creating a new documentation page

I'm not sure if this falls under "style guides" or "howto"

Draft

Tags

Example tags
  1. reader: one of "contributing-docs"/"client-docs"
  2. type: one of "intro"/"howto"/"tutorial"/"style"
  3. topic: up to 5 relevant from "git", "django", etc.
How to add them

create a front matters section at the top of the document like this:

---
tags:
  - contributing-docs
  - howto
  - git
---

File location

Voice and tone

TBD

Where it's useful

Someone adding a new documentation page can reference this to make sure they're making use of all the available functionalities of the docs site and the documentation is like the rest of the documentation.

There's a comment asking where new docs pages should go. That's also included in this guide.

Audience

contributors, technical writers

Tags

howto, style guide, documentation

shmonks commented 4 days ago

@fyliu Do you think the guide for creating a new documentation page be best in Wiki or Mkdocs?

fyliu commented 4 days ago

@shmonks I was thinkin Mkdocs. Maybe it's helpful to keep it in the wiki until it's more stabilized?

Oh I see what you mean. This might be for non-developers as well. But this guide is for adding documentation to the Mkdocs site. So I'm thinking the writer will have Mkdocs running locally on their computer. But I guess the writer can also modify the text in GitHub's website and create the PR, which would automatically fix any syntax problems in the markdown, and then another writer can review and approve.

I think most of the howto guides actually needs someone with a developer background to go through them to make sure they produce the expected outcome.

What should be the process of working on an approving this type of work? Developer create the first draft and writer review and produce a final one?

shmonks commented 4 days ago

Yes, I imagine we'd want a review - via PR probably best, then we could assign it to whoever. It sounds like Mkdocs would be the best place to have this new guide, with a link to it from the wiki.

fyliu commented 4 days ago

Once this is created, then update the following template https://github.com/hackforla/peopledepot/blob/main/.github/ISSUE_TEMPLATE/update-table.md

What's needed

Draft

Note: These steps work only for this project's database running locally in Docker container.

Shorter way

  1. Get table definition

    ./scripts/db.sh -c "\d <table_name>"

    Example table name: core_user

Long way

  1. Enter the database shell in the docker container

    ./scripts/db.sh

  2. Get list of tables

    \dt

  3. Get table definition

    \d <table_name>

Where the documentation needs to go

Where it's useful

Audience

Tags

fyliu commented 4 days ago

What's needed

Draft (very incomplete at the moment)

code block indentation

lists

Where it's useful

Where to put this

Most of the contents are for the MkDocs site, so /docs/contributing/howto/format-markdown.md But some contents are useful for GitHub as well, so also should add a link from the Wiki.

Audience

Tags