Added new section on writing Julia packages.

CONTRIBUTING.md

@@ -1,49 +1,53 @@
-Hi! Thanks for checking out Julia. If you have questions or problems, the [Julia dev list](https://groups.google.com/forum/?fromgroups#!forum/julia-dev) is a good place to post them, but you should check out the [online Julia docs](http:https://docs.julialang.org/en/latest/) first. If you have changes you'd like to contribute, you'll need a [free GitHub account](https://github.com/signup/free). (If you're reading this on GitHub, you probably already have one.) You'll also want a working copy of Julia, built from source (you can still contribute with a binary install, but it's harder and not really recommended). In list form, here's what to do to become a contributor:
+Hi! Thanks for checking out Julia. If you have questions or problems, the [Julia dev list](https://groups.google.com/forum/?fromgroups#!forum/Julia-dev) is a good place to post them, but you should check out the [online Julia docs](http:https://docs.Julialang.org/en/latest/) first. If you have changes you'd like to contribute, you'll need a [free GitHub account](https://github.com/signup/free). (If you're reading this on GitHub, you probably already have one.) You'll also want a working copy of Julia, built from source (you can still contribute with a binary install, but it's harder and not really recommended). In list form, here's what to do to become a contributor:
 
-* Join the [dev list](https://groups.google.com/forum/?fromgroups#!forum/julia-dev).
+* Join the [dev list](https://groups.google.com/forum/?fromgroups#!forum/Julia-dev).
 
 * Create a [GitHub account](https://github.com/signup/free).
 
-* [Fork Julia](https://github.com/JuliaLang/julia/fork_select).
+* [Fork Julia](https://github.com/JuliaLang/Julia/fork_select).
 
-* Build the software and libraries (the first time takes a while, but it's fast after that). Detailed build instructions are in the [README](https://github.com/JuliaLang/julia/tree/master/README.md). Julia depends on several external packages; most are automatically downloaded and installed, but are less frequently updated than Julia itself.
+* Build the software and libraries (the first time takes a while, but it's fast after that). Detailed build instructions are in the [README](https://github.com/JuliaLang/Julia/tree/master/README.md). Julia depends on several external packages; most are automatically downloaded and installed, but are less frequently updated than Julia itself.
 
 * Keep Julia current. Julia is a fast-moving target, and many details of the language are still settling out. Keep your repository up-to-date and rebase your work in progress frequently.
 
 * Relax and have fun.
 
 ## Submitting your contributions
 
-Julia now has a [package manager](https://github.com/JuliaLang/METADATA.jl). Most developers writing julia libraries are encouraged to provide them as a julia package. In case you are contributing to the core functionality or the base libraries, the process is as follows.
+### Contributing a Julia package
 
-The Julia team uses [GitHub issues](https://github.com/JuliaLang/julia/issues) to track and discuss problems, feature requests, and pull requests.
+Julia has a [package manager](https://github.com/JuliaLang/METADATA.jl). Most developers writing Julia libraries are encouraged to provide them as a Julia package.
+
+### Contributing to core functionality or base libraries
+
+The Julia team uses [GitHub issues](https://github.com/JuliaLang/Julia/issues) to track and discuss problems, feature requests, and pull requests.
 
 You can make pull requests for incomplete features to get code review. The convention is to prefix the pull request title with "WIP:" for Work In Progress, or "RFC:" for Request for Comments when work is completed and ready for merging. This will prevent accidental merging of work that is in progress.
 
 Before submitting, make sure that all tests pass by running `make testall`. Add your own tests for the new functionality in `test/`. If your contribution includes changes to Makefiles or external dependencies, make sure you can build Julia from a clean tree using `git clean -fdx` or equivalent (be careful – this command will delete any files lying around that aren't checked into git). Make sure that [Travis](http:https://www.travis-ci.org) greenlights the pull request with a `Good to merge` message.
 
-*By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).*
+*By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/Julia/tree/master/LICENSE.md).*
 
 ## Getting help
 
-While getting familiar with Julia, remember to check out [the docs](http:https://docs.julialang.org/en/latest/), keeping in mind that they are [searchable](http:https://docs.julialang.org/en/latest/search/). (If you use a script blocker then you'll have to unblock that page.) The [source code](https://github.com/JuliaLang/julia) is an excellent source of examples (and it's mostly pretty approachable). If you're still stumped, post something on [the dev list](https://groups.google.com/forum/?fromgroups#!forum/julia-dev), but you may want to search the archives first to see if there's already been a discussion about what you're stuck on.
+While getting familiar with Julia, remember to check out [the docs](http:https://docs.Julialang.org/en/latest/), keeping in mind that they are [searchable](http:https://docs.Julialang.org/en/latest/search/). (If you use a script blocker then you'll have to unblock that page.) The [source code](https://github.com/JuliaLang/Julia) is an excellent source of examples (and it's mostly pretty approachable). If you're still stumped, post something on [the dev list](https://groups.google.com/forum/?fromgroups#!forum/Julia-dev), but you may want to search the archives first to see if there's already been a discussion about what you're stuck on.
 
 ## Resources
 
 * Julia
- - **Homepage:** <http:https://julialang.org>
- - **Mailing lists:** <http:https://julialang.org/mailing_lists>
- - **IRC:** <http:https://webchat.freenode.net/?channels=julia>
- - **Source code:** <https://github.com/JuliaLang/julia>
- - **Git clone URL:** <git:https://github.com/JuliaLang/julia.git>
- - **Documentation:** <http:https://julialang.org/manual/>
+ - **Homepage:** <http:https://Julialang.org>
+ - **Mailing lists:** <http:https://Julialang.org/mailing_lists>
+ - **IRC:** <http:https://webchat.freenode.net/?channels=Julia>
+ - **Source code:** <https://github.com/JuliaLang/Julia>
+ - **Git clone URL:** <git:https://github.com/JuliaLang/Julia.git>
+ - **Documentation:** <http:https://Julialang.org/manual/>
 * Design of Julia
- - [Julia: A Fast Dynamic Language for Technical Computing](http:https://julialang.org/images/julia-dynamic-2012-tr.pdf)
+ - [Julia: A Fast Dynamic Language for Technical Computing](http:https://Julialang.org/images/Julia-dynamic-2012-tr.pdf)
 * Working with Types
- - [Some Type Patterns](https://github.com/JuliaLang/julia/wiki/Code-Patterns)
- - [The Type Hierarchy](https://github.com/JuliaLang/julia/wiki/Types-Hierarchy)
+ - [Some Type Patterns](https://github.com/JuliaLang/Julia/wiki/Code-Patterns)
+ - [The Type Hierarchy](https://github.com/JuliaLang/Julia/wiki/Types-Hierarchy)
 * Using GitHub
  - [Using Julia with GitHub (video)](http:https://www.youtube.com/watch?v=wnFYV3ZKtOg&feature=youtu.be)
- - [Using Julia on GitHub (notes for video)](https://gist.github.com/2712118#file_julia_git_pull_request.md)
+ - [Using Julia on GitHub (notes for video)](https://gist.github.com/2712118#file_Julia_git_pull_request.md)
  - [General GitHub documentation](http:https://help.github.com/)
  - [GitHub pull request documentation](http:https://help.github.com/send-pull-requests/)

doc/conf.py

@@ -42,7 +42,7 @@
 # General information about the project.
 project = u'Julia Language'
 AUTHORS = u"Jeff Bezanson, Stefan Karpinski, Viral Shah, Alan Edelman, et al."
-copyright = u'2012, '+AUTHORS
+copyright = u'2012-2013, '+AUTHORS
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/manual/index.rst

@@ -30,5 +30,6 @@
  parallel-computing
  running-external-programs
  calling-c-and-fortran-code
+ packages
  performance-tips
 

doc/manual/packages.rst

@@ -0,0 +1,136 @@
+==============
+Julia packages
+==============
+
+Where to find Julia packages
+----------------------------
+
+- An official list of packages is available, see :ref:`available-packages`.
+
+- Announcements of new packages can also be found in the `julia-users Google Groups <https://groups.google.com/forum/?fromgroups=#!forum/julia-users>`_.
+
+Installing a new Julia package
+------------------------------
+
+Installing a new package is easy. Simply type the following into Julia,
+changing ``MY_PACKAGE_NAME`` to the actual package name.
+
+.. code:: julia
+
+ Pkg.add("MY_PACKAGE_NAME")
+
+This installs the package to ``$HOME/.julia/MY_PACKAGE_NAME`` .
+
+Contributing a new Julia package
+--------------------------------
+
+In the following, replace ``MY_PACKAGE_NAME``, ``MY_GITHUB_USER``, etc. with
+the actual desired names.
+
+Creating a new Julia package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Initialize your package in Julia by running
+
+.. code:: julia
+ 
+ Pkg.new("MY_PACKAGE_NAME")
+
+This will initialize a skeleton for a new package in ``$HOME/.julia/MY_PACKAGE_NAME``.
+
+.. note::
+ This will overwrite any existing files and git repository in ``$HOME/.julia/MY_PACKAGE_NAME``.
+
+2. If you have already created a repository for your package, overwrite the
+skeleton by copying or symlinking over it. For example:
+
+.. code:: bash
+
+ rm -r $HOME/.julia/MY_PACKAGE_NAME
+ ln -s /path/to/existing/repo/MY_PACKAGE_NAME $HOME/.julia/MY_PACKAGE_NAME
+
+3. In ``REQUIRE``, list the names of all packages used by your new package. One
+package per line.
+
+4. Populate the package by filling out ``README.md`` and ``LICENSE.md``, source
+code in ``src/``, and tests in ``test/``. Ensure that each test file contains these
+lines near the beginning:
+
+.. code:: julia
+
+ using Test
+ using MY_PACKAGE_NAME
+
+5. Add a publicly accessible remote repository URL, if your package doesn't
+already have one. For example, create a new repository called
+``MY_PACKAGE_NAME.jl`` on Github and then run
+
+.. code:: bash
+
+ cd $HOME/.julia/MY_PACKAGE_NAME
+ git remote add github https://github.com/MY_GITHUB_USER/MY_PACKAGE_NAME.jl
+ 
+6. Add at least one git commit and push it to the remote repository.
+
+.. code:: bash
+
+ # Do some stuff
+ git add #new files
+ git commit
+ git push remote github
+
+Distributing a Julia package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One-time setup (once per user)
+------------------------------
+1. Fork a copy of METADATA.jl, if you haven't done so already. The forked
+repository URL should look like `https://github.com/MY_GITHUB_USER/METADATA.jl`.
+
+2. Update the local METADATA with the URL of your forked repository.
+
+.. code:: bash
+
+ cd $HOME/.julia/METADATA git remote add github
+ https://github.com/MY_GITHUB_USER/METADATA.jl
+
+Distributing a new package or new version of an existing package
+----------------------------------------------------------------
+
+1. Populate the local METADATA by running in Julia:
+
+.. code:: julia
+
+ Pkg.pkg_origin("MY_PACKAGE_NAME")
+ Pkg.patch("MY_PACKAGE_NAME")
+
+2. Update the local METADATA with the URL of your forked repository and
+create a new branch with your package in it.
+
+.. code:: bash
+ 
+ cd $HOME/.julia/METADATA
+ git branch MY_PACKAGE_NAME
+ git checkout MY_PACKAGE_NAME
+ git add MY_PACKAGE_NAME #Ensure that only the latest hash is committed
+ git commit
+
+3. Push to the remote METADATA repository
+
+.. code:: bash
+
+ git push github MY_PACKAGE_NAME
+
+4. Go to `https://github.com/MY_GITHUB_USER/METADATA.jl/tree/MY_PACKAGE_NAME`
+in your web browser. Click the 'Pull Request' button.
+
+.. image:: ../images/github_metadata_pullrequest.png
+
+5. Submit a new pull request. Ensure that the pull request goes to the
+devel branch and not master.
+
+.. image:: ../images/github_metadata_develbranch.png
+
+6. When the pull request is accepted, announce your new package to the
+Julia community on the `julia-users Google Groups <https://groups.google.com/forum/?fromgroups=#!forum/julia-users>`_.
+

doc/packages/packagelist.rst

@@ -1,3 +1,5 @@
+.. _available-packages:
+
 ********************
  Available Packages 
 ********************