diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0af268a..6676d68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,40 +1,93 @@ -CONTRIBUTING TO NewtonScript.org -================================ +# Contributing to NewtonScript.org -We welcome feedback, bug fixes, content & display improvements, and -translations. Ultimately, what gets accepted and merged into the project is up -to NewtonScript.org staff (specifically, Morgan Aldridge, the current project -maintainer), but you are encouraged to submit your improvements. +We welcome feedback, bug fixes, content & display improvements, and translations. Ultimately, what gets accepted and merged into the project is up to NewtonScript.org staff (specifically, [Morgan Aldridge](https://github.com/morgant), the current project maintainer), but you are encouraged to submit any suggestions. -WHAT YOU NEED -------------- +Please submit errors/corrections, additions, and feature requests via the project’s [issue tracker](https://github.com/NewtonScript/newtonscript.github.com/issues). + +## What You Need You will need the following to contribute: -* A [GithHub](http://github.com) account for submitting pull requests -* A familiarity with HTML5, CSS3 experience is a plus +* A [GitHub](http://github.com) account for submitting pull requests +* A familiarity with HTML5 +* Experience with CSS3 is a plus -MAKING CHANGES --------------- +## Making Changes -You will need to do the following to make changes that are most likely to be -accepted with little headache and back & forth: +Follow these steps when making changes. That way, they will most likely be accepted with few headaches and very little back and forth. -1. Fork the [newtonscript.github.com](https://github.com/NewtonScript/newtonscript.github.com) project on GitHub -2. Create a topic branch (an appropriately named branch regarding the intended changes, e.g. "new-license", "style-overhaul", or "resonsive-design-fixes") from the `master` branch -3. Make commits in logical units and with properly explanatory commit messages -4. Preview your changes in an HTML5-capable web browser to ensure nothing broke and everything is rendering appropriately. +1. Fork the [newtonscript.github.com](https://github.com/NewtonScript/newtonscript.github.com) project on GitHub. +2. Create a topic branch from the `master` branch. Name your branch appropriately, reflecting the intended changes. (e.g. “new-license”, “style-overhaul”, or “responsive-design-fixes”) +3. Make your edits (please try to conform to our [style guide](#style-guide)). +4. Make commits in logical units and with explanatory commit messages. +5. Preview your changes in an HTML5-capable web browser to ensure nothing is broken and everything is rendering correctly. -SUBMITTING CHANGES ------------------- +## Submitting Changes -When you've completed your changes and are ready for them to be merged into the -main project, you can do the following to submit them for review and likely -inclusion in NewtonScript.org: +When you’ve completed your changes and are ready to merge them into the main project, follow these steps to submit them for review. -1. Push your changes to your fork of the newtonscript.github.com project on GitHub +1. Push the changes to your fork of the [newtonscript.github.com](https://github.com/NewtonScript/newtonscript.github.com) project on GitHub 2. Submit a pull request to the [newtonscript.github.com](https://github.com/NewtonScript/newtonscript.github.com) project -That's all there is to it. If you followed the "Making Changes" guidelines and -the changes are aligned with the vision of the project, it should be a pretty -smooth process to get them merged in. \ No newline at end of file +That’s all there is to it. + +If you followed the “Making Changes” guidelines and the changes are aligned with the vision of the project, it should be a smooth process to merge them. + +## Style Guide + +### HTML + +* Please write well-formed HTML to the HTML5 specification. +* Please write pretty HTML with proper indentation for nested elements. +* Please use tabs instead of spaces for indentation. + +### Text + +* Please alphabetize referenced materials (software, source code, reference documentation, etc.) by title and authors by last name. +* For sub lists which are more appropriately listed in chronological order (e.g. lists of publication issues), please do so. +* Please use [serial commas](https://en.wikipedia.org/wiki/Serial_comma). + +### Resource Template + +The following is the template used to list referenced resources (software, source code, documentation, etc.): + +```html +
[RESOURCE DESCRIPTION]
+ +NewtonScript is an object-oriented programming language developed by Walter Smith for Apple for the Newton OS running on their MessagePad & eMate hardware. It borrows concepts from the Smalltalk, LISP, and Self programming languages with special consideration for a low memory footprint (esp. differential inheritance). In 2003 a NewtonScript interpreter, NEWT/0 was developed by Makoto Nukui allowing for its use on other platforms.
-Here you’ll find information about the language, available development tools for various platforms, libraries with NewtonScript interfaces, and programming reference materials.
+For assistance with programming in the NewtonScript language beyond the documentation provided here, it is suggested that you join the newtonscript-lang.slack.com Slack team (get an invite), join the #newtonscript channel on irc.libera.chat, tag a question with the 'newtonscript' tag on stackoverflow.com, or post to the NewtonTalk mailing list.
+ + +An alternate button bar, hierarchical menu, and scripting system (using NewtonScript) for Newton OS. Source available on GitHub.
+An alternate button bar, hierarchical menu, and scripting system (using NewtonScript) for Newton OS. Source available on GitHub.
A cross-platform IDE for Newton OS software development. Built on NEWT/0.
A Newton OS 2.1 emulator. It includes a “Relativity” feature that allows NewtonScript to call native methods from the parent OS from within the Newton OS.
A NewtonScript interpreter.
+A multi-platform NewtonScript interpreter. Matthias Melcher has also created a modified version of NEWT/0 that compiles on 64-bit architectures.
An environment for developing applications using NewtonScript and creating packages natively on a Newton OS device.
A application which can send NewtonScript commands and functions to a Newton device and then retrieve the results using a desktop or laptop computer.
+ +An Xcode language specicification (syntax highlighter) for the NewtonScript language.
+ +A SubEthaEdit and Coda Mode (syntax highlighter) for the NewtonScript language.
@@ -100,15 +143,35 @@A BBEdit and TextWrangler Codeless Language Module (syntax highlighter) for the NewtonScript language.
+A BBEdit and TextWrangler Codeless Language Module (syntax highlighter) for the NewtonScript language.
A native implementation of the NTK Inspector window for Mac OS X.
+ +A web server for Newton OS which can be scripted to generate dynamic content using NewtonScript.
+ +Apple’s original IDE for Newton OS software development.
A modern replacement for Apple’s original Newton Toolkit.
+ +This bit of code adds visual bracket matching, highlighting, and balancing functionality to the Newton Toolkit editor.
+ +A portable NewtonScript bytecode virtual machine.
An implementation of NewtonScript written in C++.
+ +A utility for exploring the Soup contained within Newton ROM images. It can preview code, strings, pictures, sounds, and more.
+ +A command line NewtonScript compiler and packager. Built on NEWT/0.
Official documentation on creating digital books and application help for the Newton, including the use of NewtonScript to customize book interaction, display, and behavior.
+ +Unofficial documentation of the inner workings of Newton OS. The following articles are NewtonScript-specific:
@@ -286,35 +495,44 @@Official documentation of Newton data formats and protocols.
Unofficial corrections to errors found in Apple's Newton Formats documentation.
Official documentation of changes and additions in Newton OS 2.1, including: NewtWorks, keyboard enhancements, grayscale imaging, graphics shapes, sound, dial-in networks, IrDA communications tool, and the eMate 300 multi-user environment.
+A preliminary draft version of Chapter 11: Miscellaneous that appears to have been intended to be added to the Newton OS 2.1 Engineering Documents, covering additions in Newton OS 2.1 that weren't, "[L]engthy enough to warrant their own chapters."
+Official documentation for the Newton OS 2.0 application programming interfaces, providing an overview and conceptual information. See the Newton Programmer’s Reference for detailed reference documentation of data structures, functions, constants, and error codes.
Official documentation covering additions and changes in the Newton OS 2.1 application programming interfaces.
Official documentation of the Newton OS 2.0 protos, methods, functions, data structures, and error codes. A companion to the Newton Programmer’s Guide.
Documentation of the NewtonScript bytecode as compiled through observation.
An overview of the NewtonScript language presented at the 2008 Lightweight Language conference in Toyko, Japan.
Official introduction & reference material for the NewtonScript language under Newton OS 2.x. You’ll probably want to start here.
An unofficial Japanese translation of Apple’s NewtonScript Programming Language reference.
+ +Apple’s Newton-specific technical journal, published six times per year from 1995-1997. The content is 70% development and 30% marketing.
Official documentation of file formats used by NTK 1.6.x for Windows and Macintosh, specifically Project files, Layout files, and native code module files.
Tips & tricks for NTK, esp. the Windows version.
Official documentation of Newton OS 2.0 user interface and how to optimize software for it, including the whys and hows.
An overview on creating and interacting with soups using NewtonScript.
+ +An overview of NewtonScript language, illustrating the differences between object oriented programming paradigms and relating how some NewtonScript features have their own particular programatic flavor.
A supplement to Newton User Interface Guidelines which specifically covers the keyboard enhancements in Newton OS 2.1.
Primarily discusses writing, linking, and packaging assembly code for Newton OS, but also covers communicating between assembly code and NewtonScript code.
+Sample NTK & MPW project for Newton OS 2.1 to control the internal serial port, incl. toggling channels and GPIO.
+ +Official sample Mac OS & Windows NTK projects for Newton OS 2.x.
+ +In 2004, Rainer Joswig spoke with Mikel Evins, a former member of Apple’s Newton group, about an early development version of Newton OS written in Lisp.
+ +Reminiscing about early Newton development, programming, and NewtonScript with Landon Dyer, a member of the original Newton team.
+ +Also available as audio files from Mac Folklore Radio.
+ + +