Release notes (#1165)

* Release notes

* Add more documentation

* Remove release announcement

* Fix typo

Author: slozier

Documentation/differences-from-c-python.md

@@ -10,6 +10,33 @@ This page documents various differences between IronPython and CPython. Since Ir
 
 * Interaction with COM objects is handled by the CLR rather than a python library binding to the native COM dlls.
 
+# Integers
+
+* `int`/`long` are separate types instead of the unified `int` type used by CPython. _Tracked by [IronLanguages/ironpython3#52](https://github.com/IronLanguages/ironpython3/issues/52)._
+
+The `long` type is no longer exposed in built-ins however it still shows up while getting the type of a long number.
+
+_CPython_
+```
+>>> type(1<<64)
+<class 'int'>
+```
+
+_IronPython_
+```
+>>> type(1<<64)
+<class 'long'>
+```
+
+However, in order to reduce compatibility issues, using `isinstance` to test if a value is an integer will work as it does in CPython:
+
+_CPython_ and _IronPython_
+```
+>>> isinstance(1<<64, int)
+True
+```
+
+
 # Strings
 
 * `str` objects are represented in UTF-16 (like all .NET strings) rather than UTF-32 used by CPython.

Documentation/upgrading-from-ipy2.md

@@ -0,0 +1,16 @@
+# Upgrading from IronPython 2 to 3
+
+IronPython 3.4 uses Python 3.4 syntax and standard libraries and so your Python code will need to be updated accordingly. There are numerous tools and guides available on the web to help porting from Python 2 to 3.
+
+## Binary Compatibility
+
+The IronPython 3 binaries are not compatible with the IronPython 2 binaries. Modules compiled with `clr.CompileModules` using IronPython 2 are not compatible and will need to be recompiled using IronPython 3.
+
+## Checking for IronPython
+
+In an effort to improve compatibility, `sys.platform` no longer returns `cli`. If you wish to check if you're running on IronPython the recommended pattern is to check that `sys.implementation.name` is equal to `ironpython`:
+
+```Python
+if sys.implementation.name == "ironpython":
+    print("IronPython!")
+```

README.md

@@ -2,11 +2,9 @@ IronPython 3
 ============
 **There is still much that needs to be done to support Python 3.x. We are working on it, albeit slowly. We welcome all those who would like to help!**
 
-The current target a Python 3.4 compatible release, although features and behaviors from later versions may be included.
-
 [Official Website](http://ironpython.net)
 
-IronPython is an open-source implementation of the Python programming language which is tightly integrated with the .NET Framework. IronPython can use the .NET Framework and Python libraries, and other .NET languages can use Python code just as easily.
+IronPython is an open-source implementation of the Python programming language which is tightly integrated with .NET. IronPython can use .NET and Python libraries, and other .NET languages can use Python code just as easily.
 
 | **What?** | **Where?** |
 | --------: | :------------: |
@@ -42,14 +40,30 @@ IronPython 3 targets Python 3, including the re-organized standard library, Unic
 This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community.
 For more information see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).
 
+## State of the Project
+The current target is Python 3.4, although features and behaviors from later versions may be included.
+
+See the following lists for features from each version of CPython that have been implemented:
+
+- [What's New In Python 3.0](WhatsNewInPython30.md)
+- [What's New In Python 3.1](WhatsNewInPython31.md)
+- [What's New In Python 3.2](WhatsNewInPython32.md)
+- [What's New In Python 3.3](WhatsNewInPython33.md)
+- [What's New In Python 3.4](WhatsNewInPython34.md)
+
+## Upgrading from IronPython 2
+For details on upgrading from IronPython 2 to 3 see the [Upgrading from IronPython 2 to 3](Documentation/upgrading-from-ipy2.md) article.
+
+## Differences with CPython
+While compatibility with CPython is one of our main goals with IronPython 3, there are still some differences that may cause issues. See [Differences from CPython](Documentation/differences-from-c-python.md) for details.
+
 ## Installation
 Builds of IronPython 3 are not yet provided.
 
 ## Build
 See the [building document](Documentation/building.md)
 
-Since the main development is on Windows, Mono bugs may inadvertantly be introduced
-- please report them!
+Since the main development is on Windows, bugs on other platforms may inadvertently be introduced - please report them!
 
 ## Supported Platforms
 IronPython 3 targets .NET Framework 4.6, .NET Core 2.1/3.1 and .NET 5.0. The support for .NET Core and .NET 5 will follow the lifecycle defined on [.NET Core and .NET 5 Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core).