atxtechbro / atxtechbro/dotfiles

Global-first principle: Medium-term improvements

Open
#800 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement refactor
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Overview
This issue tracks medium-term improvements needed to better align with the global-first configuration principle established in #793.

## Medium-term Improvements

### 1. Separate dotfiles-specific from globally useful configurations
- [ ] Create clear directory structure: `local/` for dotfiles-specific, `global/` for universal
- [ ] Audit all configurations and categorize them appropriately
- [ ] Move configurations to their proper locations
- [ ] Update setup.sh to handle both types correctly

### 2. Create clear directory structure distinguishing local vs global
- [ ] Design and document the new directory structure
- [ ] Implement `global/` directory for universally useful configurations
- [ ] Implement `local/` directory for repository-specific items
- [ ] Create migration script to reorganize existing files

### 3. Update setup scripts to install globally by default
- [ ] Refactor setup.sh to prioritize global installations
- [ ] Add flags for local-only installations when needed
- [ ] Create separate setup functions for global vs local configs
- [ ] Ensure backward compatibility during transition

### 4. Document configuration exceptions
- [ ] Create `EXCEPTIONS.md` documenting why certain configs remain local
- [ ] Add inline documentation for any local-only configurations
- [ ] Establish review process for new local configurations
- [ ] Create guidelines for when local configuration is acceptable

## Additional Improvements

### 5. Create configuration discovery mechanism
- [ ] Implement system to detect which configurations can be made global
- [ ] Add reporting on current global vs local split
- [ ] Create dashboard or status command to show configuration state

### 6. Improve worktree handling
- [ ] Investigate ways to share global configs across worktrees
- [ ] Reduce duplication between main repo and worktrees
- [ ] Document best practices for worktree-specific overrides

## Success Criteria
- Clear separation between local and global configurations
- Documentation explains the rationale for any local configurations
- Setup process is intuitive and defaults to global
- Migration path is smooth for existing users

## Related Issues
- #793 - Establish global-first configuration principle
- #798 - Audit: Configurations violating global-first principle
- #799 - Global-first principle: Immediate fixes needed

These improvements require more planning and coordination but will significantly improve the alignment with the global-first principle.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the global-first principle in #793 and the related audits in #798 and #799, then inspect setup.sh and the current configuration layout. Map which configurations are global or local before planning the directory and migration work. Done means the separation, setup behavior, exceptions documentation, and migration path meet the listed success criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
bash, shell
Domain
tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.