<commit_before>=================
Developer's Guide
=================

.. _dev-reference-label:

Developer's Guide Overview
--------------------------
This article describes the guidelines to be followed by developers working on
SunPy. You if you are thinking of contributing to SunPy please read the following
carefully.

Version Control
---------------

Source-code for SunPy is managed using `Git <http://git-scm.com>`_, 
a Distributed Version Control system. Code branches are hosted on 
`GitHub.com <http://github.com/sunpy/sunpy>`_, a free project hosting  website 
for Open-Source software.

Creating Your Own Repo 
^^^^^^^^^^^^^^^^^^^^^^

**Overview**

Each person contributing to SunPy should create their own code repository on
GitHub by forking the master repository or repo.eas All development is then done on that 
fork, using topic branches to isolate work on different features. New 
contributers can then initiate pull requests to have their code incorporated 
into the SunPy master repository. Regular contributers can become members of the 
`SunPy team <https://github.com/sunpy>`_ on GitHub. Code will be reviewed by regular 
contributors and comments will usually be provided before code is accepted.

**Getting Started**

Creating your own repo on GitHub is easy to do. If you followed the SunPy installation
instructions you should already have git installed. Go ahead and create a free account 
on `create an account on GitHub <https://github.com/signup/free>`_. Github has some 
`great resources to help <https://help.github.com/>`_. Here is a quick overview of the
process. 

**Adding an SSH key to GitHub**

Next, you need to tell GitHub who you are. In order to push any code to GitHub 
you need to create a public SSH key and associate it with your GitHub account. 
For instructions on how this is done, see the article on GitHub on 
`Setting up git <http://help.github.com/set-up-git-redirect>`_ under 
"Set Up SSH Keys". You only need to do this once, although if you plan to 
work from multiple computers you will need to go through the process for each 
computer you wish to work on. Once you have created your account and 
associated a public SSH key it, you are ready to go.

**Using HTTPS**

If you do not fancy using SSH you can access GitHub using HTTP/HTTPS.
A few things to note.
Using HTTP only allows cloning of public repositories, while HTTPS allows cloning of private repositories but also allows you to have push access.
This way you can type in your username and password to access your repositories.

**Identifying yourself**

Begin by identifying yourself to git (so all of your commits have this information) and logging in to GitHub: :: 

 git config --global user.name "Firstname Lastname"
 git config --global user.email "<EMAIL>"
 
**Forking SunPy**

Each contributer to SunPy has their own copy of the SunPy master repo. When
working on the code, changes are made to this copied repo, and only when the
changes are completed, and have been verified to work, are they pull requested back
to the upstream repo. GitHub provides a simple mechanism to setup your own
personal repo by providing an option to `fork a repository 
<http://help.github.com/fork-a-repo/>`_. When you create a fork of a GitHub
project, a copy of the repo will automatically be created for you, and a link
will be provided which you can use to download the code to your machine and
begin working on it.

To begin, fork the main SunPy repo on GitHub by clicking on the `Fork` button 
on the `SunPy project page <https://github.com/sunpy/sunpy>`_

Next, you need to download the forked repository. Clone the fork to your 
local machine, edit and run: ::

 git clone git@github.com:your_username/sunpy.git

or: ::

 git clone http://github.com/sunpy/sunpy.git

By default your fork of the repo on GitHub is identified by the name `origin`.
In order to keep the fork up to date with the main repo, it is useful to add it
as a `remote` in git: ::

 git remote add upstream https://github.com/sunpy/sunpy.git

To stay up to date you can grab the latest changes to the SunPy master using
the commands: ::

 git pull upstream master

This will merge the upstream code automatically with your code so you don't need to worry
about it overwriting your changes. After running either of these commands, 
your local copy of your personal repo is just a copy of the main repo.
This is the same procedure that you will use in the future to keep yourself syncronized with the
main repo. To make sure everything is setup correctly, let's make some changes
to our personal local repo and push those to our personal repo on GitHub. Go ahead and modify one
of the files, or create a new file (and then run :command:`git add`). 

Commit and push the changes to GitHub: ::

 git commit -a -m "My first commit"
 git push

You local repo is now synced with GitHub and ahead of the main repo as it contains 
your personal contribution. Remember to commit after you've done a unit of work (i.e.
often). This will make it easier for you (in the future) and everyone else to understand 
what you are doing. Also make sure to make your commit statements clear and understandable.

**Installing SunPy**

In order to use the version of SunPy located  in your personal repository. 
You need to install it using the `setup.py` script located in the top-level folder.
The `setup.py` script has several flags: ::
`develop` : Installs SunPy and builds all external libraries. 
`build` or `build_ext`:  (Re)Builds the external libraries.
`clean --all`: Cleans all build files 

Use the `setup.py` script like so: ::

 sudo python setup.py develop<commit_msg>Adding instructions to change enviroments for a conda installation<commit_after>=================
Developer's Guide
=================

.. _dev-reference-label:

Developer's Guide Overview
--------------------------
This article describes the guidelines to be followed by developers working on
SunPy. You if you are thinking of contributing to SunPy please read the following
carefully.

Version Control
---------------

Source-code for SunPy is managed using `Git <http://git-scm.com>`_, 
a Distributed Version Control system. Code branches are hosted on 
`GitHub.com <http://github.com/sunpy/sunpy>`_, a free project hosting  website 
for Open-Source software.

Creating Your Own Repo 
^^^^^^^^^^^^^^^^^^^^^^

**Overview**

Each person contributing to SunPy should create their own code repository on
GitHub by forking the master repository or repo.eas All development is then done on that 
fork, using topic branches to isolate work on different features. New 
contributers can then initiate pull requests to have their code incorporated 
into the SunPy master repository. Regular contributers can become members of the 
`SunPy team <https://github.com/sunpy>`_ on GitHub. Code will be reviewed by regular 
contributors and comments will usually be provided before code is accepted.

**Getting Started**

Creating your own repo on GitHub is easy to do. If you followed the SunPy installation
instructions you should already have git installed. Go ahead and create a free account 
on `create an account on GitHub <https://github.com/signup/free>`_. Github has some 
`great resources to help <https://help.github.com/>`_. Here is a quick overview of the
process. 

**Adding an SSH key to GitHub**

Next, you need to tell GitHub who you are. In order to push any code to GitHub 
you need to create a public SSH key and associate it with your GitHub account. 
For instructions on how this is done, see the article on GitHub on 
`Setting up git <http://help.github.com/set-up-git-redirect>`_ under 
"Set Up SSH Keys". You only need to do this once, although if you plan to 
work from multiple computers you will need to go through the process for each 
computer you wish to work on. Once you have created your account and 
associated a public SSH key it, you are ready to go.

**Using HTTPS**

If you do not fancy using SSH you can access GitHub using HTTP/HTTPS.
A few things to note.
Using HTTP only allows cloning of public repositories, while HTTPS allows cloning of private repositories but also allows you to have push access.
This way you can type in your username and password to access your repositories.

**Identifying yourself**

Begin by identifying yourself to git (so all of your commits have this information) and logging in to GitHub: :: 

 git config --global user.name "Firstname Lastname"
 git config --global user.email "<EMAIL>"
 
**Forking SunPy**

Each contributer to SunPy has their own copy of the SunPy master repo. When
working on the code, changes are made to this copied repo, and only when the
changes are completed, and have been verified to work, are they pull requested back
to the upstream repo. GitHub provides a simple mechanism to setup your own
personal repo by providing an option to `fork a repository 
<http://help.github.com/fork-a-repo/>`_. When you create a fork of a GitHub
project, a copy of the repo will automatically be created for you, and a link
will be provided which you can use to download the code to your machine and
begin working on it.

To begin, fork the main SunPy repo on GitHub by clicking on the `Fork` button 
on the `SunPy project page <https://github.com/sunpy/sunpy>`_

Next, you need to download the forked repository. Clone the fork to your 
local machine, edit and run: ::

 git clone git@github.com:your_username/sunpy.git

or: ::

 git clone http://github.com/sunpy/sunpy.git

By default your fork of the repo on GitHub is identified by the name `origin`.
In order to keep the fork up to date with the main repo, it is useful to add it
as a `remote` in git: ::

 git remote add upstream https://github.com/sunpy/sunpy.git

To stay up to date you can grab the latest changes to the SunPy master using
the commands: ::

 git pull upstream master

This will merge the upstream code automatically with your code so you don't need to worry
about it overwriting your changes. After running either of these commands, 
your local copy of your personal repo is just a copy of the main repo.
This is the same procedure that you will use in the future to keep yourself syncronized with the
main repo. To make sure everything is setup correctly, let's make some changes
to our personal local repo and push those to our personal repo on GitHub. Go ahead and modify one
of the files, or create a new file (and then run :command:`git add`). 

Commit and push the changes to GitHub: ::

 git commit -a -m "My first commit"
 git push

You local repo is now synced with GitHub and ahead of the main repo as it contains 
your personal contribution. Remember to commit after you've done a unit of work (i.e.
often). This will make it easier for you (in the future) and everyone else to understand 
what you are doing. Also make sure to make your commit statements clear and understandable.

**Installing SunPy**

In order to use the version of SunPy located  in your personal repository. 
You need to install it using the `setup.py` script located in the top-level folder.
The `setup.py` script has several flags: ::
`develop` : Installs SunPy and builds all external libraries. 
`build` or `build_ext`:  (Re)Builds the external libraries.
`clean --all`: Cleans all build files 

Use the `setup.py` script like so: ::

 sudo python setup.py develop

If you are interested in having different versions of sunpy in your
machine and you want to switch from one to another you could use
virtual enviroments. This is an easy task if you used conda as your
python package manager.

After a standard conda installation, :ref:`assuming you have also installed
the latest stable version of sunpy <main-install>`, you then proceed to create a new enviroment
as::

 conda create -n sunpy-dev python=2.7 sunpy

This will create a new enviroment called `sunpy-dev` with all of the
dependencies needed by sunpy. We the proceed to change to the new
enviroment::

 source activate sunpy-dev

Then we need to remove the stable version from this enviroment ::

 conda remove sunpy

to then install the version in your git repository ::

 cd to/sunpy/git/repository
 python setup.py develop

At this stage you can use the development version in which you are
working on.
If you want to go back to the stable installation you can just change
the enviroment by ::

 source deactivate
{'fraction_non_alphanumeric': 0.0669364629704573, 'fraction_numerical': 0.00016187778227438285, 'mean_word_length': 3.9862792574656982, 'pattern_counts': {'":': 0, '<': 22, '<?xml version=': 0, '>': 22, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5856294', 'n_tokens_mistral': 3288, 'n_tokens_neox': 3106, 'n_words': 1926}