Permalink
Browse files

Add basic documentation (#422)

  • Loading branch information...
slozier committed Aug 30, 2018
1 parent 1e0fd92 commit 1e72a567c9cb4d371cf5884d86d75c90c557e96f
View
@@ -0,0 +1,28 @@
# Contributing a patch
The steps to contribute a change are:
* Fork the IronPython3 repository as mentioned at [Getting the Sources](Documentation/getting-the-sources.md)
* Make your changes on your machine, ensure ```make.ps1 test-all``` runs successfully, and commit your changes.
* Push the commits to your fork. This way your name will be the author of the commit in the main IronPython3 tree (once the commits are pulled into the main tree).
* Create a pull request on Github, this will initiate a code review and CLA signing request
* The IronPython team will review, and possibly request changes, to your PR
* Once all comments/questions/concerns have been addressed, your PR will be merged.
Also, [Collaborative Github Workflow](http://www.eqqon.com/index.php/Collaborative_Github_Workflow) has a very good description of the workflow and tips and tricks when contributing to a project hosted on GitHub.
# Ideas for contributions
For our first release, we are currently aiming for a Python 3.4 compatible version of IronPython. To that end we have created checklists in order to help keep track of what remains to be done:
* [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
Suggestions for first time contributors:
* Updating documentation (such as checking off completed features in the above lists).
* Trying out failing tests to identify and/or fix the cause of the failures.
* [List of good first issues](https://github.com/IronLanguages/ironpython3/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
View
@@ -0,0 +1,45 @@
# Building IronPython3
To build IronPython3 you will need the .NET SDK (minimum 4.5), a .NET Core SDK (minimum 2.0) and if building on Linux/macOS you will need [Mono](https://mono-project.com).
See [Getting the Sources](getting-the-sources.md) for information on getting the source for IronPython3.
## Building from Visual Studio
Visual Studio 15.2 or above is required to build IronPython3
* Open `c:\path\to\ironpython3\IronPython.sln` solution file
* Select the configuration options (Release,Debug, etc)
* Press Ctrl+Shift+B or F6 to build the solution
## Building from the command line
IronPython3 uses PowerShell to run the build and testing from the command line. You can either use a PowerShell directly, or prefix the commands below with `powershell` on Windows, or `pwsh` on Linux/macOS.
On Linux/macOS you will need to install [PowerShell](https://github.com/PowerShell/PowerShell/releases)
Change the working directory to the path where you cloned the sources and run `.\make.ps1`
By default, with no options, make.ps1 will build Release mode binaries. If you would like to build debug binaries, you can run `.\make.ps1 debug`
Other options available for `make.ps1` are
```
-configuration (debug/release) The configuration to build for
-platform (x86/x64) The platform to use in running tests
-runIgnored Run tests that are marked as ignored in the .ini manifests
-frameworks A comma separated list of frameworks to run tests for
(use nomenclature as is used in msbuild files for TargetFrameworks)
```
There are also other targets available for use with packaging and testing, most come in debug and release (default) versions, such as `package-debug` and `package`
```
package Creates packages supported by the current platform
stage Stages files ready for packaging
test-* Runs tests from `all` categories, `ironpython` specific tests,
`cpython` tests from the CPython stdlib test suite, `smoke` a small
set of tests
```
If the build is successful the binaries are stored in ironpython3/bin/{ConfigurationName}/{Framework}
@@ -0,0 +1,7 @@
This page documents various differences between IronPython and CPython.
* IRONPYTHONSTARTUP is used instead of PYTHONSTARTUP
* IRONPYTHONPATH is used instead of PYTHONPATH
* Interaction with COM objects is handled by the CLR rather than a python library binding to the native COM dlls.
@@ -0,0 +1,156 @@
# Feature Symbols
Feature Symbols (named FEATURE_{feature name}, all caps) are compilation symbols defined for features whose availability vary across platforms that IronPython supports. The symbols are defined in Build/{framework}.props file, which get included by all .csproj files that contribute to IronPython.
**The following list needs a major update**
The following symbols are currently used:
### FEATURE_ANSICP
System.Globalization.TextInfo.ANSICodePage
### FEATURE_APARTMENTSTATE
System.Threading.ApartmentState
### FEATURE_APPLICATIONEXCEPTION
System.ApplicationException
### FEATURE_ASSEMBLY_CODEBASE
System.Reflection.Assembly.CodeBase
### FEATURE_ASSEMBLY_LOCATION
System.Reflection.Assembly.Location
### FEATURE_ASSEMBLY_RESOLVE
Runtime assembly resolution (System.AppDomain.AssemblyResolve event).
### FEATURE_ASSEMBLYBUILDER_DEFINEDYNAMICASSEMBLY
System.Reflection.Emit.AssemblyBuilder.DefineDynamicAssembly
### FEATURE_ASYNC
(currently unused)
### FEATURE_BASIC_CONSOLE
Basic Console features like Console.WriteLine, Console.ReadLine.
### FEATURE_CODEDOM
System.CodeDom
### FEATURE_COM
### FEATURE_CONFIGURATION
Configuration files (System.Configuration).
### FEATURE_CUSTOM_MODIFIERS
Reflection of required and optional custom modifiers.
### FEATURE_CUSTOM_TYPE_DESCRIPTOR
System.ComponentModel.ICustomTypeDescriptor interface.
### FEATURE_DBNULL
System.DBNull type.
### FEATURE_DRIVENOTFOUNDEXCEPTION
System.IO.DriveNotFoundException
### FEATURE_DYNAMIC_EXPRESSION_VISITOR
System.Linq.Expressions.DynamicExpressionVisitor
### FEATURE_ENCODING
Full encoding support: code pages, decoder/encoder fallbacks.
### FEATURE_EXCEPTION_STATE
System.Threading.ThreadAbortException.ExceptionState
### FEATURE_FILESYSTEM
Full file system (Directory, File, Path, FileStream, etc.)
### FEATURE_FULL_CONSOLE
Full Console APIs including stdin, stdout, stderr streams, colors, etc.
### FEATURE_FULL_CRYPTO
### FEATURE_FULL_NET
### FEATURE_ICLONEABLE
System.ICloneable
### FEATURE_IPV6
System.Net.Sockets.SocketOptionName.IPv6Only
### FEATURE_LCG
### FEATURE_LOADWITHPARTIALNAME
System.Reflection.Assembly.LoadWithPartialName
### FEATURE_METADATA_READER
DLR metadata reader available.
### FEATURE_MMAP
System.IO.MemoryMappedFiles
### FEATURE_NATIVE
Native code interop: P/Invokes, CTypes, etc.
### FEATURE_OS_SERVICEPACK
System.OperatingSystem.ServicePack
### FEATURE_PDBEMIT
Ability to emit PDB files.
### FEATURE_PROCESS
Processes, AppDomains, process-wide environment variables.
### FEATURE_READONLY_COLLECTION_INTERFACE
System.Collections.Generic.IReadOnlyList
### FEATURE_READONLY_DICTIONARY
System.Collections.ObjectModel.ReadOnlyDictionary
### FEATURE_REFEMIT
Reflection.Emit.
### FEATURE_REGISTRY
### FEATURE_REMOTING
Remoting (MarshalByRefObject).
### FEATURE_SECURITY_RULES
System.Security.SecurityRuleSet and related (e.g. System.Security.SecurityRulesAttribute)
### FEATURE_SERIALIZATION
Serialization - Serializable attribute, ISerializable interface.
### FEATURE_SORTKEY
System.Globalization.SortKey
### FEATURE_STACK_TRACE
System.Diagnostics.StackTrace, System.Diagnostics.StackFrame.
### FEATURE_SYNC_SOCKETS
System.Net.Sockets.
### FEATURE_THREAD
Threads, ThreadAbortException.
### FEATURE_TYPE_EQUIVALENCE
System.Type.IsEquivalentTo
### FEATURE_TYPE_INFO
System.Reflection.TypeInfo
### FEATURE_TYPECONVERTER
System.ComponentModel.TypeConverter and TypeConverterAttribute types.
### FEATURE_VARIANCE
Covariance and contravariance of generic interface and delegate parameters.
### FEATURE_WARNING_EXCEPTION
System.ComponentModel.WarningException
### FEATURE_WIN32EXCEPTION
System.ComponentModel.Win32Exception
### FEATURE_WPF
### FEATURE_XMLDOC
XML documentation available at runtime.
@@ -0,0 +1,62 @@
The main IronPython3 git repository is at [http://github.com/IronLanguages/ironpython3](http://github.com/IronLanguages/ironpython3).
## Downloading the sources
You can [download a zipped copy](http://github.com/IronLanguages/ironpython3/zipball/master) of the latest IronPython3 sources as well.
### Installing GIT
The following links include resources for installing and using GIT:
* [GitHub guides](http://help.github.com/)
* [GIT documentation](http://www.kernel.org/pub/software/scm/git/docs/git.html) - If you have never used GIT, reading the [tutorial](http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html) first will be a big help to finding your way around.
* [Cheat sheet](http://cheat.errtheblog.com/s/git) - Quick reference for commonly used commands
* [Collaborative Github Workflow](http://www.eqqon.com/index.php/Collaborative_Github_Workflow) - very good description of the workflow and tips and tricks when contributing to a project hosted on GitHub.
* [Jimmy's Cheatsheet](http://tinyurl.com/jimmygitcheat)
### Creating a local GIT repository
You will first need to fork the IronPython3 project. [Creating a fork](https://help.github.com/fork-a-repo/) is recommended as it will allow you to contribute patches back easily. Click the "Fork" button on [https://github.com/IronLanguages/ironpython3/](https://github.com/IronLanguages/ironpython3/). This should create your personal fork, with a website like http://github.com/janedoe/ironpython3 (where janedoe is your github username).
You can now use the git command-line client with many Linux distributions, Mac OS, Cygwin, and Windows (msysgit) to get the sources onto your local computer using the following commands:
```
git config --global branch.autosetupmerge true
git config --global user.name "Jane Doe"
git config --global user.email janedoe@example.com
git clone git@github.com:janedoe/ironpython3.git
cd ironpython3
git remote add ironpython3 git://github.com/IronLanguages/ironpython3.git
git pull ironpython3 master
```
At a later date, to get the latest updates from the IronPython3 project, run the following command in the ironpython3 directory created above:
```
git pull ironpython3 master
```
If there is a merge conflict, edit the unmerged files to remove the conflict markers, and then run the following command:
```
git commit -a
```
To push your changes back to your fork and make them public, use `git push`.
### Working without a fork
You can skip creating a fork if you only want to browse the sources. In that case, you can clone the project directly as such:
```
git clone git://github.com/IronLanguages/ironpython3.git
git pull
```
### Initialize submodules
The DLR (Dynamic Language Runtime) is a submodule of the ironpython3 repository, you need to initialize after cloning the repository.
```
git submodule update --init`
```
For more information there is an excellent tutorial on [getting started with git](http://kylecordes.com/2008/04/30/git-windows-go/)
@@ -0,0 +1,26 @@
# TDD
Bug fixes should be acompanied by a test that shows that the bug has been fixed. If the bug fix is fixing something that is covered by a test in the C Python test suite (Src\StdLib\Lib\test) and that test is not currently enabled, try enabling the test in Src\IronPythonTest\Cases\*.ini depending on the type of test it is.
Most PR's will not be accepted if there is not a test included.
# Coding conventions
* We have a .editorconfig file with the coding conventions used in the project. Please use an editor that honors these settings.
* Use [.NET Framework conventions for all identifiers](http://msdn2.microsoft.com/en-us/library/ms229002.aspx).
* There is no specific guideline for naming private fields in this document; we prefix field names with underscores (e.g. <code>private string _fooBar;</code>) so that use of the fields is easily distinguishable as a field access as opposed to a local variable access.
* If you're not sure about some convention try to find out in the rest of the IronPython code or ask in the list.
* Use `/*!*/` for method parameters and instance fields that should never be null. [Spec# annotations](http://research.microsoft.com/specsharp).
* Do not use public fields (Base::algorithm, buffer). Use properties if it is necessary to expose the field or private/internal visibility otherwise.
* Use `readonly` if the field is not mutated after the object is constructed.
* Auto properties are to be used when possible instead of private fields with wrapping properties
* String interpolation should use used instead of calls to `String.Format`
# Validating the changes
The following commands will build and run all the tests that are required to pass. If you get any failures, do report them to the mailing-list to see if they are expected or not. This command can usually run without any failures.
```
./make.ps1 test-all
```

0 comments on commit 1e72a56

Please sign in to comment.