From 28105ed870d0a9e6278276e9e045f01ff1652e42 Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Mon, 4 Mar 2024 11:51:51 -0500 Subject: [PATCH 1/6] Add more instructions to contributing --- docs/contributing.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index c40953fbd..d0db449e8 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -30,7 +30,38 @@ Documentation is written as a series of markdown files nested by topic in direct ## Adding new documentation -_Instructions forthcoming on how to find the right place to add your docs._ +As outlined in [this IA issue](https://github.com/AlexsLemonade/OpenScPCA-analysis/issues/61), we have several sections of documentation. +The diagram below shows the directory structure for the docs, for now considering only the top three directory levels. +The directory names as written in the IA issue are shown in parentheses. -Files and directories should be named with all lowercase letters using `-`, not `_`, where needed. +Each bold bullet point in the IA issue is a directory, and each plain-text bullet is a markdown file. +Consult the IA issue and this directory structure to determine where to place new markdown file. + +If the IA indicates this file should be in an even more nested directory, don't worry about it for now; later, we will add additional nested directores as more documentation comes together. + +Files and directories should be named with all lowercase letters and use `-`, not `_`, where needed. **Be sure to consult the [style guide](./general-style-guide.md) when writing your documentation.** + +``` +├── welcome (Welcome to OpenScPCA) +│  ├── accessing-resources (Getting access to resources) +│  └── getting-started (Getting Started) +├── technical-setup (Setting up) +│   └── environment-setup (Getting access to resources) +├── communications-tools (Communicating within the Project) +│   ├── github-discussions (Github Discussions) +│   └── github-issues (Github Issues) +│   └── writing-issues (Writing good issues) +├── contributing-to-analyses (Contributing to an analysis) +│   ├── analysis-modules (Analysis modules) +│   ├── doing-analyses (Doing an analysis) +│   │   └── working-with-git (Working with git) +│   ├── planning-analyses (Planning your analysis) +│   └── pull-requests (Creating Pull Requests) +├── software-platforms (Software tools) +│   ├── aws +│   ├── docker +│   └── lsfr +└── troubleshooting-faq (Getting help & FAQ) +``` + From 159b38403f4cf04a5a7d6535d90c1f728bcff43b Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Mon, 4 Mar 2024 11:52:00 -0500 Subject: [PATCH 2/6] more stubs --- docs/communications-tools/github-discussions/.gitkeep | 0 docs/communications-tools/github-issues/.gitkeep | 0 docs/communications-tools/github-issues/writing-issues/.gitkeep | 0 docs/contributing-to-analyses/analysis-modules/.gitkeep | 0 docs/contributing-to-analyses/doing-analyses/.gitkeep | 0 .../doing-analyses/working-with-git/.gitkeep | 0 docs/contributing-to-analyses/planning-analyses/.gitkeep | 0 docs/contributing-to-analyses/pull-requests/.gitkeep | 0 docs/software-platforms/aws/.gitkeep | 0 docs/software-platforms/docker/.gitkeep | 0 docs/software-platforms/lsfr/.gitkeep | 0 docs/technical-setup/environment-setup/.gitkeep | 0 docs/welcome/accessing-resources/.gitkeep | 0 docs/welcome/getting-started/.gitkeep | 0 14 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/communications-tools/github-discussions/.gitkeep create mode 100644 docs/communications-tools/github-issues/.gitkeep create mode 100644 docs/communications-tools/github-issues/writing-issues/.gitkeep create mode 100644 docs/contributing-to-analyses/analysis-modules/.gitkeep create mode 100644 docs/contributing-to-analyses/doing-analyses/.gitkeep create mode 100644 docs/contributing-to-analyses/doing-analyses/working-with-git/.gitkeep create mode 100644 docs/contributing-to-analyses/planning-analyses/.gitkeep create mode 100644 docs/contributing-to-analyses/pull-requests/.gitkeep create mode 100644 docs/software-platforms/aws/.gitkeep create mode 100644 docs/software-platforms/docker/.gitkeep create mode 100644 docs/software-platforms/lsfr/.gitkeep create mode 100644 docs/technical-setup/environment-setup/.gitkeep create mode 100644 docs/welcome/accessing-resources/.gitkeep create mode 100644 docs/welcome/getting-started/.gitkeep diff --git a/docs/communications-tools/github-discussions/.gitkeep b/docs/communications-tools/github-discussions/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/communications-tools/github-issues/.gitkeep b/docs/communications-tools/github-issues/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/communications-tools/github-issues/writing-issues/.gitkeep b/docs/communications-tools/github-issues/writing-issues/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/analysis-modules/.gitkeep b/docs/contributing-to-analyses/analysis-modules/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/doing-analyses/.gitkeep b/docs/contributing-to-analyses/doing-analyses/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/doing-analyses/working-with-git/.gitkeep b/docs/contributing-to-analyses/doing-analyses/working-with-git/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/planning-analyses/.gitkeep b/docs/contributing-to-analyses/planning-analyses/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/pull-requests/.gitkeep b/docs/contributing-to-analyses/pull-requests/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/software-platforms/aws/.gitkeep b/docs/software-platforms/aws/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/software-platforms/docker/.gitkeep b/docs/software-platforms/docker/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/software-platforms/lsfr/.gitkeep b/docs/software-platforms/lsfr/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/technical-setup/environment-setup/.gitkeep b/docs/technical-setup/environment-setup/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/welcome/accessing-resources/.gitkeep b/docs/welcome/accessing-resources/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/welcome/getting-started/.gitkeep b/docs/welcome/getting-started/.gitkeep new file mode 100644 index 000000000..e69de29bb From 001689edca3b1ac43b6f1bc3ffc73e70cd3d8c11 Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Mon, 4 Mar 2024 11:56:57 -0500 Subject: [PATCH 3/6] mention img --- docs/contributing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.md b/docs/contributing.md index d0db449e8..9f55442a5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -40,6 +40,7 @@ Consult the IA issue and this directory structure to determine where to place ne If the IA indicates this file should be in an even more nested directory, don't worry about it for now; later, we will add additional nested directores as more documentation comes together. Files and directories should be named with all lowercase letters and use `-`, not `_`, where needed. +If you are adding new images/visual aids for documentation, place them in the `img` directory (not shown in the diagram below). **Be sure to consult the [style guide](./general-style-guide.md) when writing your documentation.** ``` @@ -64,4 +65,3 @@ Files and directories should be named with all lowercase letters and use `-`, no │   └── lsfr └── troubleshooting-faq (Getting help & FAQ) ``` - From 641fa0d05c4ddee20a09c4e84f699d211da2eb5d Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Mon, 4 Mar 2024 12:30:52 -0500 Subject: [PATCH 4/6] more gitkeeps --- docs/contributing-to-analyses/merging-prs/.gitkeep | 0 docs/contributing-to-analyses/pr-review-process/.gitkeep | 0 .../pull-requests/filing-pull-requests/.gitkeep | 0 .../pull-requests/filing-pull-requests/before-filing/.gitkeep | 0 .../filing-pull-requests/creating-pull-requests/.gitkeep | 0 5 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/contributing-to-analyses/merging-prs/.gitkeep create mode 100644 docs/contributing-to-analyses/pr-review-process/.gitkeep create mode 100644 docs/contributing-to-analyses/pull-requests/filing-pull-requests/.gitkeep create mode 100644 docs/contributing-to-analyses/pull-requests/filing-pull-requests/before-filing/.gitkeep create mode 100644 docs/contributing-to-analyses/pull-requests/filing-pull-requests/creating-pull-requests/.gitkeep diff --git a/docs/contributing-to-analyses/merging-prs/.gitkeep b/docs/contributing-to-analyses/merging-prs/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/pr-review-process/.gitkeep b/docs/contributing-to-analyses/pr-review-process/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/pull-requests/filing-pull-requests/.gitkeep b/docs/contributing-to-analyses/pull-requests/filing-pull-requests/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/pull-requests/filing-pull-requests/before-filing/.gitkeep b/docs/contributing-to-analyses/pull-requests/filing-pull-requests/before-filing/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/contributing-to-analyses/pull-requests/filing-pull-requests/creating-pull-requests/.gitkeep b/docs/contributing-to-analyses/pull-requests/filing-pull-requests/creating-pull-requests/.gitkeep new file mode 100644 index 000000000..e69de29bb From 59e62dd1f890b03c2832d9816be6f28c6c418439 Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Mon, 4 Mar 2024 12:31:10 -0500 Subject: [PATCH 5/6] remove gh discussions directory --- docs/communications-tools/github-discussions/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/communications-tools/github-discussions/.gitkeep diff --git a/docs/communications-tools/github-discussions/.gitkeep b/docs/communications-tools/github-discussions/.gitkeep deleted file mode 100644 index e69de29bb..000000000 From 20ef32f50aced07ea040ba8815baa82c18b9a2bd Mon Sep 17 00:00:00 2001 From: "Stephanie J. Spielman" Date: Mon, 4 Mar 2024 12:31:28 -0500 Subject: [PATCH 6/6] directory structure updates --- docs/contributing.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 9f55442a5..49ad9fb0f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -31,7 +31,7 @@ Documentation is written as a series of markdown files nested by topic in direct ## Adding new documentation As outlined in [this IA issue](https://github.com/AlexsLemonade/OpenScPCA-analysis/issues/61), we have several sections of documentation. -The diagram below shows the directory structure for the docs, for now considering only the top three directory levels. +The diagram below shows the directory structure for the docs. The directory names as written in the IA issue are shown in parentheses. Each bold bullet point in the IA issue is a directory, and each plain-text bullet is a markdown file. @@ -50,7 +50,6 @@ If you are adding new images/visual aids for documentation, place them in the `i ├── technical-setup (Setting up) │   └── environment-setup (Getting access to resources) ├── communications-tools (Communicating within the Project) -│   ├── github-discussions (Github Discussions) │   └── github-issues (Github Issues) │   └── writing-issues (Writing good issues) ├── contributing-to-analyses (Contributing to an analysis) @@ -58,7 +57,12 @@ If you are adding new images/visual aids for documentation, place them in the `i │   ├── doing-analyses (Doing an analysis) │   │   └── working-with-git (Working with git) │   ├── planning-analyses (Planning your analysis) -│   └── pull-requests (Creating Pull Requests) +│   ├── pull-requests (Creating Pull Requests) +│ │ └── filing-pull-requests (Filing a PR) +│ │ ├── before-filing (Before filing a PR) +│ │ └── creating-pull-requests (Creating the PR) +│   ├── pr-review-process (PR Review Process) +│ └── merging-prs (Merging a PR) ├── software-platforms (Software tools) │   ├── aws │   ├── docker