ourPLCC · StoneyJackson · Nov 15, 2023 · Nov 15, 2023 · Nov 15, 2023 · Nov 15, 2023
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -2,46 +2,24 @@
 
 PLCC is a Programming Language Compiler Compiler.
 
-Please see [our wiki](https://github.com/ourPLCC/plcc/wiki) for documentation.
-
-To contact us, report a problem, or make a suggestion, please open an issue
-here: <https://github.com/ourPLCC/plcc/issues>.
-
-For information about how to contribute to this project, please see CONTRIBUTING.md.
-
-## Automated Tests
-
-### Dependencies
-
-* PLCC
-* Bash 5+
-* [bats 1.2+](https://bats-core.readthedocs.io/en/latest/index.html).
-
-### Running the tests
-
-Run the tests...
-
-```bash
-tests/run
-```
-
-### Running the tests inside the official container.
-
-Build and run the PLCC container...
-
-```bash
-containers/plcc/build.bash
-containers/plcc/run.bash
-```
-
-You are now running inside the PLCC container. Now run the tests.
-
-```bash
-/plcc/tests/run
-```
-
-### Writing Tests
-
-See [Bats documentation](https://bats-core.readthedocs.io/en/latest/index.html).
-Place tests in `tests/plcc`. See existing tests for examples.
-
+General
+- Licensed under [GPLv3.0 or higher](LICENSE)
+- [Open an issue](https://github.com/ourPLCC/plcc/issues) to contact us, report a problem, or make a suggestion.
+
+User Guide
+- [Getting Started](docs/User/Getting-Started.md)
+- [Native PLCC Installation](docs/User/Native-PLCC-Installation.md)
+- [PLCC-in-Docker](docs/User/PLCC-in-Docker.md)
+- [Use PLCC](docs/User/Use.md)
+- [Dependencies](docs/User/Dependencies.md)
+- [Version numbers](docs/User/Version-numbers.md)
+- [Download the PLCC-paper.pdf](docs/PLCC-paper.pdf)
+
+Developer Guide
+- [Contribute Using a Fork](docs/Developer/Contribute-Using-a-Fork.md)
+- [Contribute Without a Fork](docs/Developer/Contribute-Without-a-Fork.md)
+- [Testing](docs/Developer/Testing.md)
+
+Maintainer Guide
+- [Merging PRs](docs/Maintainer/Merging-PRs.md)
+- [Release](docs/Maintainer/Release.md)
diff --git a/docs/Developer/Contribute-Using-a-Fork.md b/docs/Developer/Contribute-Using-a-Fork.md
@@ -0,0 +1,136 @@
+First, because this project is licensed under GPLv3, all contributions must be licensed under the same license.
+By contributing to this project, you agree to the [Developer Certificate of Origin](https://developercertificate.org/); essentially certifying that the work you are submitting may be licensed under this project's license: GPLv3.
+
+## Overview
+
+- Never commit to master.
+- Only commit work to personal feature branches.
+- Always cut feature branches from the most recent version of master.
+- Contribute changes by publishing your feature branch and issuing a
+  pull-request to master in the original repository.
+
+There are several ways to contribute. Below I describe two common ways.  The
+first assumes you do not have write privileges to the repository, the second
+are for those who do have write privileges. Anyone can use the first. Only
+those who have been granted write privileges can use the second. If you would
+like to apply for write privileges, please open an issue requesting access, and
+explain why.
+
+## Contributing with a fork
+
+This procedure does not require any special privileges to contribute changes.
+
+In the example below, I'll be fixing a typo in the README.md of this project.
+Below are values that are unique to this example. You could replace them with
+values that make sense in your context.
+
+1. From GitHub, fork this project <https://github.com/ourPLCC/>.
+
+```bash
+# 2. Clone your fork (first time only; replace the URL with your fork's URL).
+git clone https://github.com/StoneyJackson/PROJECT.git
+
+# 3. Change into the root of the project.
+cd PROJECT
+
+# 4. Create a remote pointing to the original project (first time only).
+git remote add upstream https://github.com/ourPLCC/PROJECT.git
+
+# 5. Make sure you are on master.
+git checkout master
+
+# 6. Make sure you have the most recent version of master.
+git pull upstream master
+
+# 7. Push the most recent version of master to your fork.
+git push origin master
+
+# 8. Create a feature branch (name your branch something meaningful).
+git checkout -b sj-fix-typo-in-readme
+
+# 9. Make the change(s) using your favorite tools (replace these commands with whatever makes sense).
+vim README.md
+
+# 10. Stage your changes
+git add .
+
+# 11. Commit your changes
+git commit -v
+
+# 12. Publish your feature branch
+git push -u origin sj-fix-typo-in-readme
+
+# 13. Return to master branch
+git checkout master
+```
+
+14. In your fork on GitHub, create a pull-request from your feature branch
+    (in this case, sj-fix-typo-in-readme) to master in the original project.
+
+15. In the pull-request, request a review by placing @ourPLCC/core in a
+    comment.
+
+## Contributing with write privileges
+
+If you have write privileges, you can contribute using the fork procedure
+described above, or modify the fork procedure as follows:
+
+- Don't fork.
+- Don't create an upstream remote.
+- Update your local master as in steps 5 and 6 above, but by pulling from origin's master (instead of upstream's master):
+    ```
+    git checkout master
+    git pull origin master
+    ```
+
+## Updating a pull-request using a fork
+
+We try to keep our git graph linear so that it is more easily understood.  If
+someone else's pull-request is merged before yours, you will likely be asked to
+update your pull-request. This section describes how you do that.
+
+Let's assume that your pull-request is associated with the feature branch
+`sj-fix-typo-in-readme`. Let's also assume that you are working in a fork,
+and you have a remote named `upstream` that refers to the original project.
+If you followed the "Contributing with a fork" procedure above, then you
+should be ready to follow these instructions.
+
+```bash
+git checkout master
+git pull upstream master
+git push origin master
+git checkout sj-fix-typo-in-readme
+git merge master
+```
+
+The last command tries to merge the changes from master into your feature
+branch (the currently checked out branch).  Your changes may not be compatible
+with the new changes in master. If Git detects a lexical conflict, it will stop
+the process and will expect you to resolve the conflicts. Checkout GitHub's
+documentation on [Resolving a merge conflict using the command
+line](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line).
+
+Even if Git does not detect a conflict and finished merging "successfully",
+there may be a logical conflict. The only way to detect logical conflicts is
+through testing (e.g., manual inspection, running automated tests, manual
+testing, etc.). Perform suitable tests and make and commit any necessary fixes.
+
+Once you are satisfied, update your pull-request by pushing your changes to the
+associated feature branch in your fork.
+
+```
+git push origin sj-fix-typo-in-readme
+```
+
+This will automatically update the pull-request. Return to the pull-request on
+GitHub and request a review from @ourPLCC/core.
+
+## Updating a pull-request with write privileges
+
+Same as "Updating a pull-request using a fork", except pull changes from origin
+instead of upstream:
+
+```bash
+git checkout master
+git pull origin master
+```
diff --git a/docs/Developer/Contribute-Without-a-Fork.md b/docs/Developer/Contribute-Without-a-Fork.md
@@ -0,0 +1,69 @@
+You must have write permissions on this repository to use this workflow.
+
+## Clone this project
+
+```bash {.line-numbers}
+git clone https://github.com/ourPLCC/plcc.git
+cd plcc
+```
+
+You only need to clone the repository once. Or if you ever delete your local clone.
+
+
+## Proposing a Change
+
+In the commands below, replace `feature` with a short descriptive name for your branch.
+
+```bash {.line-numbers}
+git switch master
+git pull origin master
+git switch -c feature
+vim ... ; mv ... ; mkdir ... ; rm ...
+git add .
+git commit -m "short descriptive message"
+git push -u origin feature
+... # Navigate to URL printed to create a merge-request.
+```
+
+- 1-3: Create a new branch based on the most recent copy of `master`.
+- 4: Use your favorite tools to make and test changes.
+- 5-6: Stage and commit your changes.
+- 7-8: Publish your branch and create a pull-request.
+
+
+## Update a Feature Branch
+
+If you are asked to update a feature branch with new changes in master.
+
+```bash {.line-numbers}
+git switch master
+git pull origin master
+git switch feature
+git merge master
+vim ... ; mv ... ; mkdir ... ; rm ...
+git add .
+git merge --continue
+git push origin feature
+```
+
+- 1-4: Merge the new changes into your feature branch.
+- 5-7: Resolve conflicts if any; otherwise move on to 8.
+- 8: Push the merged branch. This also updates the merge-request.
+
+## Cleaning up
+
+After your pull-request is merged, you can clean up your local clone as follows.
+
+```bash {.line-numbers}
+git switch master
+git pull origin master
+git branch -d feature
+git push origin --delete feature
+git pull --prune
+```
+
+- 1-2: Update master with the new changes.
+- 3: Delete the feature branch locally. If this gives you an error, and you're sure your changes are in master, repeat the command with -D (capital d).
+- 4: Delete the feature branch remotely. If the remote branch was already deleted, you'll get an error which you can safely ignore.
+- 5: Delete the local reference to the remote branch you just deleted.
+- 6: Remove the reference to the remote branch that was just deleted.
diff --git a/docs/Developer/Testing.md b/docs/Developer/Testing.md
@@ -0,0 +1,36 @@
+# Testing
+
+## Dependencies
+
+* PLCC
+* Bash 5+
+* [bats 1.2+](https://bats-core.readthedocs.io/en/latest/index.html).
+
+## Running the tests
+
+Run the tests...
+
+```bash
+tests/run
+```
+
+## Running the tests inside the official container.
+
+Build and run the PLCC container...
+
+```bash
+containers/plcc/build.bash
+containers/plcc/run.bash
+```
+
+You are now running inside the PLCC container. Now run the tests.
+
+```bash
+/plcc/tests/run
+```
+
+## Writing Tests
+
+See [Bats documentation](https://bats-core.readthedocs.io/en/latest/index.html).
+Place tests in `tests/plcc`. See existing tests for examples.
+
diff --git a/docs/Maintainer/Merging-PRs.md b/docs/Maintainer/Merging-PRs.md
@@ -0,0 +1,4 @@
+When a PR is merged, a release is automatically cut. So, ensure all tests are passing, and then perform a squash merge writing a good commit message. This commit message:
+
+1. Must follow Conventional Commits since it will be used to determine the next version number.
+2. Will become the release notes for the new release. So identify bugs fixed, new features, and BREAKING CHANGES made in the pull request. If you don't know what they are, ask the author. If you still don't know, don't merge.
diff --git a/docs/Maintainer/Release.md b/docs/Maintainer/Release.md
@@ -0,0 +1 @@
+Release are cut automatically when a PR is merged. The new release number is determined by Conventional Commit 1.0.0 messages and follow SemVer 2.0.0.
diff --git a/PLCC-paper.pdf → docs/PLCC-paper.pdf b/PLCC-paper.pdf → docs/PLCC-paper.pdf
diff --git a/docs/User/Dependencies.md b/docs/User/Dependencies.md
@@ -0,0 +1,24 @@
+# Dependencies
+
+## Dependencies for Native PLCC Installation
+
+* Bash
+    * Bash ***or*** Command Prompt are needed to run PLCC's scripts.
+    * Supported Versions: 5+
+* Java
+    * Supported Versions:
+        * min: 11.0.21
+        * max: latest stable build
+* Python
+    * PLCC supports the most recent release of each minor version that was released in the last 3 years.
+    * Supported Versions:
+        * min: 3.5.10
+        * max: latest stable build
+
+## Dependencies for PLCC-in-Docker
+
+* Docker
+
+## Dependencies for Development
+
+* GitPod
diff --git a/docs/User/Find-and-interpret-version-numbers.md b/docs/User/Find-and-interpret-version-numbers.md
@@ -0,0 +1,8 @@
+You can determine what version of PLCC you have by running
+
+
+```bash
+plcc --version
+```
+
+Or you can view the contents of the VERSION text file located in the directory where PLCC lives on your system.
diff --git a/docs/User/Getting-Started.md b/docs/User/Getting-Started.md
@@ -0,0 +1,16 @@
+There are two options for using PLCC. Each has its advantages and disadvantages.
+
+* [Native PLCC Installation](Native-PLCC-Installation.md)
+    * Advantages
+        * Choice of what version of dependencies (Python, Java, and shell) to use.
+    * Disadvantages
+        * Must properly install and configure dependencies and PLCC.
+        * Dependencies are shared with other software on your system, which could lead to maintenance challenges in the future.
+* [PLCC-in-Docker (Docker Container)](PLCC-in-Docker.md)
+    * Advantages
+        * Docker is the only dependency you need to install.
+        * PLCC container, preinstalled with dependencies, is downloaded, installed, and ran in a single command.
+        * PLCC's dependencies are not shared with other software on your system, so future maintenance is easier.
+    * Disadvantages
+        * On a non-linux platform, Docker will require a fair amount of resources to run (4-8 GB memory).
+        * To control versions of dependencies (Python, Java, and Bash), you'd have to create a custom Docker container.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Release are cut automatically when a PR is merged. The new release number is determined by Conventional Commit 1.0.0 messages and follow SemVer 2.0.0.