Preparing initial release: Merge pull request #38 from John-Robbins/p…

…rep-release - Created the release steps document. - Created the initial change log. - Created the initial CONTRIBUTING document. - Yet another editing pass on the web site. - 😅 the details - Added the contributing documentation. - Numerous small fixes.
John-Robbins · Sep 7, 2024 · ce8ddc7 · ce8ddc7
2 parents 852943a + 02791cd
commit ce8ddc7
Show file tree

Hide file tree

Showing 11 changed files with 191 additions and 13 deletions.
diff --git a/.vscode/ltex.hiddenFalsePositives.en-US.txt b/.vscode/ltex.hiddenFalsePositives.en-US.txt
@@ -24,3 +24,5 @@
 {"rule":"POSSESSIVE_APOSTROPHE","sentence":"^\\QThe examples directory contains a number of sample Tiny BASIC programs for your enjoyment.\\E$"}
 {"rule":"AS_IS_VBG","sentence":"^\\QError #330: IF is missing the relational operator but found '%s'.\\E$"}
 {"rule":"POSSESSIVE_APOSTROPHE","sentence":"^\\QThe examples directory holds sample Tiny BASIC programs for your enjoyment.\\E$"}
+{"rule":"UNLIKELY_OPENING_PUNCTUATION","sentence":"^\\Q:steam_locomotive: Change Log\\E$"}
+{"rule":"WORD_CONTAINS_UNDERSCORE","sentence":"^\\Q:steam_locomotive: Change Log\\E$"}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,9 @@
+# :steam_locomotive: Change Log
+
+---
+
+## 0.9.0 (2024-09-06)
+
+---
+
+- The initial public release of Tiny BASIC in Python! See the [documentation](https://john-robbins.github.io/tbp/) for complete usage.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,5 @@
+# Contributing
+
+---
+
+Thank you so much for all contributions to Tiny BASIC in Python! The complete contributing documentation can be found here: [https://john-robbins.github.io/tbp/contributing](https://john-robbins.github.io/tbp/contributing).
diff --git a/docs/docs/command-language.md b/docs/docs/command-language.md
@@ -4,7 +4,9 @@ nav_order: 4
 layout: default
 permalink: tbp-command-language
 ---
-<!-- markdownlint-disable MD026 MD025-->
+<!-- markdownlint-disable-next-line -->
+# tbp Command Language
+{:.no_toc}
 
 1. TOC
 {:toc}
@@ -134,7 +136,7 @@ The option command uses the following format:
 %opt required_option (true | false | <none>)
 ```
 
-Note that instead of requiring you to type out "true" or "false", they can be abbreviated to "t" or "f".
+Note that instead of requiring you to type out `true` or `false`, they can be abbreviated to `t` or `f`.
 
 Executing just the `%opt required_option` will show you the current state of that option.
 
@@ -156,7 +158,15 @@ Interpreter state: State.FILE_STATE
 
 The first line shows the source line about to be processed. The first part of the output shows the lexical scanner result. A token, `[IF (300,4)]` shows the token scanned followed by the line the token is on (i.e., the line number), which is 300 in this case. The second number is the column for the token, which is used in error reporting.
 
-The parsing section shows the breakdown of the language items, or the abstract syntax tree representation. Finally, it shows the current state of the state machine inside the tree walking interpreter.
+The parsing section shows the breakdown of the language items, or the abstract syntax tree representation. Finally, it shows the current state of the state machine inside the tree walking interpreter. The interpreter states are in the table below.
+
+| State | Description |
+|-------|-------------|
+|`LINE_STATE` | The user is typing lines in directly at the tbp prompt.|
+|`FILE_STATE` | When reading a file from disk into memory. |
+|`RUNNING_STATE`| Executing a program. |
+|`BREAK_STATE`| Stopped at a breakpoint.|
+|`ERROR_FILE_STATE` | When reading lines out of a file, but had an earlier error so tbp continues parsing and reporting additional errors, but don't execute any code after finishing the file.|
 
 When running a program in memory, the logging output shows you each line as it is executed. In the example below, you can see that the [`GOTO`](tb-language#goto---jump-to-line) was executed moving the instruction pointer from line 900 to line 180.
 
@@ -275,7 +285,7 @@ You can look at all the *initialized* variables with the `%v` command. In fact,
 tbp:>RUN
 Breakpoint: 200
 [200 IF J = 0 THEN GOTO 265]
-DEBUG(200):>%vars
+DEBUG(200):>%v
 C=3         I=1         J=27        N=10        S=256
 DEBUG(200):>
 ```

diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
@@ -0,0 +1,139 @@
+---
+title: Contributing
+nav_order: 6
+layout: default
+permalink: contributing
+---
+<!-- markdownlint-disable-next-line -->
+# Contributing
+{:.no_toc}
+
+1. TOC
+{:toc}
+
+---
+
+Thank you so much for any and all contributions to Tiny BASIC in Python! As this is my first full Python project, I am sure there are many mistakes, even though I tried to follow best practices. Thank you for helping me learn!
+
+## Before Starting
+
+Before submitting a pull request, please help me out by doing the following.
+
+- File an issue explaining the bug or mistake in the code.
+- If the issue is not following best practices, please explain what I did wrong or include a link to a website/repository showing why I need to make the change.
+- This is all about me learning after all, so I appreciate the pointers.
+
+## Setting Up Your Development Environment
+
+All my development occurred on Python version 3.12.1, but any higher versions will work as the CI GitHub Actions are using 3.12.5.
+
+### macOS Sonoma and Linux
+
+Note: I haven't tested these scripts on Linux, but they should work. Let me know if they don't.
+
+In the `./tools` directory are two shell scripts I used to jump set up my environment. First ensure that you don't have a virtual environment active. If you do, execute `deactivate`. In the tbp code root directory, run the following three commands in your terminal.
+
+```bash
+chmod +x ./tools/venv-setup.sh
+chmod +x ./tools/dev-setup.sh
+./tools/venv-setup.sh
+```
+
+Close and reopen the terminal to activate the `.tbp-venv` virtual environment. In the tbp code root directory, run the following command.
+
+```bash
+./tools/dev-setup.sh
+```
+
+This script will upgrade `pip`, install the developer tools, and make an editable install where you can develop all you want.
+
+### Windows
+
+Note that I don't have a Windows computer, so I am going off memory and reading Activate.ps1, with these steps. Please file a bug if these are not correct!
+
+For Windows, you will need to do the script steps manually in the tbp code root directory at a PowerShell command prompt.
+
+First look to see if the `VIRTUAL_ENV` is set, which says you have a virtual environment already active. Run the Windows equivalent to `deactivate` to disable that virtual environment.
+
+In your PowerShell command prompt, execute the following commands to create a virtual environment for tbp.
+
+```powershell
+python3 -m venv .tbp-venv
+.\.tbp-venv\bin\activate
+```
+
+You may have to shut down and restart PowerShell.
+
+In your PowerShell command prompt, in the tbp code root directory, execute the following commands.
+
+```powershell
+python -m pip install $dryrun --upgrade pip
+python -m pip install $dryrun .[dev]
+python -m pip install $dryrun --editable .
+```
+
+## Key Development Notes
+
+<!-- markdownlint-disable-next-line -->
+<span style="color:red">**UNIT TESTS AND CODE COVERAGE ARE EVERYTHING!**</span>
+
+At the time of this writing, there are 280 unit tests and the combined operating system code coverage of 99.92%. For any pull requests, I'll obviously be checking that any code changes have tests that execute the code. _No coverage, no merge._
+
+If you have a version of `make` installed, the root directory has the `Makefile` that automates a ton of work for you. Simply running `make` will do the work of running `mypy`, `ruff`, `pylint`, `coverage.py`, and `pytest`.
+
+Here's what the output looks like on macOS. `Makefile` is your best friend when developing tbp.
+
+```text
+% make
+mypy --config-file pyproject.toml src/ tests/
+Success: no issues found in 28 source files
+ruff check --config ./pyproject.toml src/ tests/
+All checks passed!
+pylint --rcfile pyproject.toml src/ tests/
+
+--------------------------------------------------------------------
+Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)
+
+coverage run -m pytest --maxfail=1 -console_output_style=classic --junit-xml=.test-results.xml
+============================= test session starts ==============================
+platform darwin -- Python 3.12.1, pytest-8.3.2, pluggy-1.5.0
+rootdir: /Users/johnrobbins/Code/tbp
+configfile: onsole_output_style=classic
+plugins: anyio-4.4.0
+collected 280 items
+
+tests/cmd_lang_test.py ..........                                        [  3%]
+tests/debugger_test.py .....................                             [ 11%]
+tests/driver_test.py ........................                            [ 19%]
+tests/helpers_test.py ...........                                        [ 23%]
+tests/interpreter_test.py .............................................. [ 40%]
+...........................                                              [ 49%]
+tests/lang_test.py ..                                                    [ 50%]
+tests/linter_test.py ..........................                          [ 59%]
+tests/memory_test.py .                                                   [ 60%]
+tests/parser_test.py ................................................... [ 78%]
+.................                                                        [ 84%]
+tests/scanner_test.py ...................................                [ 96%]
+tests/symboltable_test.py ........                                       [ 99%]
+tests/tokens_test.py .                                                   [100%]
+
+------ generated xml file: /Users/johnrobbins/Code/tbp/.test-results.xml -------
+============================= 280 passed in 1.05s ==============================
+coverage report --precision=2 --show-missing --sort=Cover --skip-covered
+Name                        Stmts   Miss Branch BrPart   Cover   Missing
+------------------------------------------------------------------------
+src/tbp/helpers.py             82      8     22      2  90.38%   21-23, 187-191, 235-236
+src/tbp/driver.py             216      4    108      6  96.91%   86->88, 89->91, 138, 166, 311-312, 389->exit, 421->exit
+src/tbp/astprinter.py         142      3     28      2  97.06%   111-112, 277
+src/tbp/interpreter.py        499      5    186      7  98.25%   201->205, 356->360, 415->420, 578->exit, 600->603, 1047-1048, 1134-1136
+src/tbp/parser.py             275      3    116      2  98.72%   359->364, 486-488, 509->526
+src/tbp/languageitems.py      170      1      8      1  98.88%   192
+src/tbp/scanner.py            242      1    128      3  98.92%   211->exit, 320, 356->360
+tests/interpreter_test.py     510      0     14      2  99.62%   885->exit, 904->exit
+------------------------------------------------------------------------
+TOTAL                        3994     25    870     25  98.97%
+
+19 files skipped due to complete coverage.
+coverage lcov
+Wrote LCOV report to .coverage.lcov
+```
diff --git a/docs/docs/faq.md b/docs/docs/faq.md
@@ -57,3 +57,5 @@ permalink: faq
     |`interpreter.py`| The tree walking interpreter that takes care of execution and debugging.|
     |`driver.py` | "Drives" the `Interpreter` class and handles the tbp command language.|
     |`__main__.py`|The entry point for the command line program.|
+
+    See [Contributing](Contributing) for how to get setup for development.
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -4,7 +4,8 @@ nav_order: 2
 layout: default
 permalink: getting-started
 ---
-<!-- markdownlint-disable MD026 MD025-->
+<!-- markdownlint-disable-next-line -->
+# Getting Started
 
 1. TOC
 {:toc}

diff --git a/docs/docs/tb-language.md b/docs/docs/tb-language.md
@@ -5,10 +5,8 @@ layout: default
 mathjax: true
 permalink: tb-language
 ---
-<!-- markdownlint-disable MD026 MD025-->
-
 <!-- markdownlint-disable-next-line -->
-#Tiny BASIC Language
+# Tiny BASIC Language
 {:.no_toc}
 
 1. TOC
@@ -44,7 +42,7 @@ If you looked closely at the second example, you might have noticed that Tiny BA
 
 You can execute Tiny BASIC statements in two ways. At the tbp prompt, `tbp:>`, you can directly execute a statement like [`RUN`](#run---execute-the-program-in-memory), which is more like a command. If the line begins with a number, it's considered a program line and tbp stores it in memory for later execution.
 
-If a statement starts with `%`, that is a [tbp command language](tbp-command-language) statement. Those are what you can use for executing the [debugger](tbp-command-language#the-tiny-basic-in-python-debugger), running the linter, and setting various options in tbp. You can read more about those command in the Command Language section.
+If a statement starts with `%`, that is a [tbp command language](tbp-command-language) statement. Those are what you can use for executing the [debugger](tbp-command-language#the-tiny-basic-in-python-debugger), running the [linter](tbp-command-language#linting-lint), and setting various options in tbp. You can read more about those command in the Command Language section.
 
 ## Expressions
 
@@ -170,7 +168,7 @@ I treat that as a warning. The original Tiny BASIC had a scheme where it stored
 
 ### `PRINT` - Output
 
-It might be nice show data to the user of your awesome Tiny BASIC program and that's your `PRINT` statement, which you can abbreviate to `PR for space savings. This is the one statement that can work with string data. You may pass any sort of mix of strings, expressions, or the two print separators,`,` and `;`.
+It might be nice show data to the user of your awesome Tiny BASIC program and that's your `PRINT` statement, which you can abbreviate to `PR` for space savings. This is the one statement that can work with string data. You may pass any sort of mix of strings, expressions, or the two print separators,`,` and `;`.
 
 ```text
 tbp:>PRINT A

diff --git a/docs/docs/thoughts.md b/docs/docs/thoughts.md
@@ -1,6 +1,6 @@
 ---
 title: Project Notes
-nav_order: 5
+nav_order: 6
 layout: default
 permalink: project-notes
 ---

diff --git a/docs/index.md b/docs/index.md
@@ -11,7 +11,7 @@ permalink: /
 {:.fs-9}
 
 {:.fs-6.fw-300}
-Dress up in your best corduroy suit or patterned jumper, it's time for some disco, so put the Bee Gees latest 45 on the turn table!
+Dress up in your best corduroy suit or patterned jumper, it's time for some disco, so put the Bee Gees latest 45 on the turn table and let's get coding like your grandparents!
 
 OK, you really don't have to dress in the epitome of 1970s fashions, do the bump, or listen to disco, but you will enjoy programming like it's 1976! Tiny BASIC in Python (tbp) is an implementation of the [Tiny BASIC language](https://en.wikipedia.org/wiki/Tiny_BASIC) that ran on the Intel 8080, the Motorola 6800, and the MOS Technologies 6502 processors and fit into 4K of memory.
 
@@ -23,7 +23,7 @@ Any problems/confusion? Please file an [issue](https://github.com/John-Robbins/t
 
 ## Some Usage Hints
 
-The links on the left of this page have detailed discussion of installation, usage, the Tiny BASIC language, and the tbp command language that controls the programming environment.
+The links on the left of this page have detailed discussion of installation, usage, the [Tiny BASIC language](tb-language), and the [tbp command language](tbp-command-language) that controls the programming environment.
 
 ### Prompts and Command Line Editing
 

diff --git a/tools/releasing.md b/tools/releasing.md
@@ -0,0 +1,12 @@
+
+# Releasing tbp
+
+- On a branch do the following.
+  - Update the version numbers in `./src/tbp/__init__.py` and `./docs/data/version.yml`.
+  - Update ./CHANGELOG.md with changes if not already in the UNRELEASED section.
+- Create PR with above changes.
+- Merge into main.
+- Verify all build, linting, testing, and website deployment work.
+- Create a new tag on the main branch with the format `#.#.#` AKA SemVer.
+- Create a new release on GitHub copying over the relevant changes.
+- Make sure the new release has the _latest_ mark.