diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index fd223928..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -Please see . diff --git a/README.md b/README.md index 37fa0dc0..2879bb1d 100644 --- 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: . - -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 new file mode 100644 index 00000000..efce32db --- /dev/null +++ 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 . + +```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 new file mode 100644 index 00000000..9a6b24b7 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/Developer/Testing.md b/docs/Developer/Testing.md new file mode 100644 index 00000000..dd8b128e --- /dev/null +++ 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 new file mode 100644 index 00000000..986bac68 --- /dev/null +++ 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 new file mode 100644 index 00000000..1809ecc8 --- /dev/null +++ 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 b/docs/PLCC-paper.pdf similarity index 100% rename from PLCC-paper.pdf rename to docs/PLCC-paper.pdf diff --git a/docs/User/Dependencies.md b/docs/User/Dependencies.md new file mode 100644 index 00000000..a4e73928 --- /dev/null +++ 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 new file mode 100644 index 00000000..f830c80e --- /dev/null +++ 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 new file mode 100644 index 00000000..0f0ddd3d --- /dev/null +++ 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. diff --git a/docs/User/Native-PLCC-Installation.md b/docs/User/Native-PLCC-Installation.md new file mode 100644 index 00000000..2572a8db --- /dev/null +++ b/docs/User/Native-PLCC-Installation.md @@ -0,0 +1,46 @@ +# Native PLCC Installation + +> Version 2.0.0 or above + +See [Dependencies](Dependencies.md) for supported versions of Java, Python, and shells. + +1. You need Command Prompt (on Windows) or a Bash shell to run PLCC's scripts. +2. Install Java JDK 11 or higher. We recommend [OpenJDK](https://openjdk.java.net/). + * Ensure `java` and `javac` are in your PATH environment variable and are available from your shell. If not add the folder that contains `java` and `javac` to your PATH environment variable. + * Ensure `java --version` and `javac --version` report the same version. If not, in the PATH environment variable, move the folder containing `java` and `javac` to the front of your PATH. +3. Install Python 3.8 or higher + * Ensure `python` is in your PATH and available in your shell. If not, add the folder containing python to your PATH. + * Ensure `python --version` reports the version of Python you installed. If not, you may need to adjust your PATH. + * You may need to try `python3` or `py` depending on your operating system. +4. Download a copy of PLCC. You can do this in two different ways. + 1. Use git to clone https://github.com/ourPLCC/plcc into its new home, and checkout the tag for the version you want to use. + ```bash + git clone https://github.com/ourPLCC/plcc.git + cd plcc + git checkout v3.1.0 + ``` + 2. Download a zip of the desired version of PLCC from the [PLCC Releases page](https://github.com/ourPLCC/plcc/releases), and extract it into its new home on your computer. +5. Identify the PLCC's `src` directory within the directory (or subdirectories) created when you extracted the zip. +6. Define a new environment variable named LIBPLCC whose value is the full path to PLCC's src directory. +7. Add the full path to PLCC's src directory to beginning of the PATH environment variable. + +# Upgrading + +## Via Git + +If you used git to download and install PLCC, checkout the tag for the new version you want to use. For example, in the root of the PLCC directory... + +```bash +git checkout v4.0.0 +``` + +Read the CHANGELOG to see if there is anything else you need to do to upgrade to the new version. + +## Via Zip + +If you downloaded and extracted a zip when you installed PLCC, download a zip for the new version. Then, either... + +1. Replace the old version with the new one by deleting the existing folder and then extracting the new zip into the same location +2. Or, extract the new version into a different directory and then update environment variable's accordingly (PATH and PLCCLIB). + +Read the CHANGELOG to see if there is anything else you need to do to upgrade to the new version. diff --git a/docs/User/PLCC-in-Docker.md b/docs/User/PLCC-in-Docker.md new file mode 100644 index 00000000..02933fcf --- /dev/null +++ b/docs/User/PLCC-in-Docker.md @@ -0,0 +1,32 @@ +## 1. Install Docker Desktop for your operating system. + +* https://docs.docker.com/desktop/install/windows-install/ +* https://docs.docker.com/desktop/install/mac-install/ +* https://docs.docker.com/desktop/install/linux-install/ + +## 2. Run Docker Docker if it's not already running. + +## 3. Start a shell with your code. + +On Windows, open a command prompt (e.g., Start menu -> type `cmd`), and position it in the directory where you want to work. Then run the following. + +```bash +docker run -it --rm -v "%cd%:/code" -w /code ghcr.io/ourplcc/plcc:latest +``` + +On MacOS or Linux, open a terminal running a standard shell (e.g., bash, zsh, etc), and position it in the directory where you want to work. Then run the following + +```bash +docker run -it --rm -v "$PWD:/code" -w /code ghcr.io/ourplcc/plcc:latest +``` + +## 4. Use PLCC inside the container. + +Now you are inside a bash shell, positioned in /code, within Alpine linux, with PLCC and its dependencies installed, and the current directory (/code) contains all your code. You can now use all of PLCC's commands. + +Feel free to use your favorite editor on your host machine to edit files. + +## 5. `exit` when done. + +When you are done, type `exit`. All the files you generated will be in your current working directory and its subdirectories. + diff --git a/docs/User/Use.md b/docs/User/Use.md new file mode 100644 index 00000000..36989341 --- /dev/null +++ b/docs/User/Use.md @@ -0,0 +1,17 @@ +Whether you are running inside of Docker, a terminal running a Bash shell, a PowerShell, or a Windows command prompt, the commands should be the same. + +Here's a summary of the PLCC commands: + +``` +plcc runs plcc.py on 'file' +plccmk [-c] [file]: runs plcc.py on 'file' and uses javac to compile all + of the resulting Java files in the Java directory. + The optional '-c' flag will remove all previous + Java files if there were any + The 'file' name defaults to 'grammar' +scan: Runs the Java/Scan program (only scan for tokens) +parse: Runs the Java/Parser program (only scan and parse) +rep: Runs the Java/Rep program + (scan, parse, and enter read-eval-print loop) +rep-t: Runs the Java/Rep program with the trace flag +``` \ No newline at end of file diff --git a/docs/User/Version-numbers.md b/docs/User/Version-numbers.md new file mode 100644 index 00000000..236ab56b --- /dev/null +++ b/docs/User/Version-numbers.md @@ -0,0 +1,26 @@ +## What version of PLCC am I running? + +You can determine what version of PLCC you have by running + + +```bash +plcc --version +``` + +## What does PLCC's version number mean? + +PLCC uses [Semantic Versioning](https://semver.org/). Each release has a version number containing three numeric components: MAJOR.MINOR.PATCH. These components encode important information about the types of changes that have been made since the last release. This helps you decide if and when to upgrade to newer versions and how much time you should spend reading the CHANGELOG. + +## What's with the `-dev.0`? + +In between official releases are development releases. The version number for a development release is suffixed with `-dev.0`. For example, `2.3.4-dev.0`. If you are using a development copy and you are not a developer, consider installing an official release instead. + +## Should I upgrade? + +Here is a quick guide on how to evaluate each release based on its version number. + +- Previous release `2.3.4` -> New release `2.3.5`: Only the PATCH component has been incremented. The new release only contains bugfixes --- no new features and no breaking changes. This is a reasonably safe upgrade and you may not even want to read the CHANGELOG. + +- `2.3.5` -> `2.4.0`: The MINOR component has been incremented and the PATCH was reset to 0. This means that the new release includes one or more new features as well as zero or more bugfixes --- but no breaking changes. Upgrading to this new version is a bit more risky than the patch release in the previous example. New features may have introduced new bugs that were not caught before releasing. However, it does not contain a change that is expected to interfere with existing functionality. So it's still a reasonably safe upgrade. And you may want to read the CHANGELOG to see what the new features are. + +- `2.4.0` -> `3.0.0`: MAJOR has been incremented and the other components reset. This means one or more breaking changes have been introduce. New features and bugfixes may also be included. In this case reading the CHANGELOG is a must. Something in the public interface has changed that may break how you were using the project before. Maybe a feature was renamed or removed. Or maybe the way it behaves is different. Make sure you know what you are getting into before upgrading to a new major release.