|
| 1 | +.. _astropy-org-contribute: |
| 2 | + |
| 3 | +Contribute to Astropy |
| 4 | +===================== |
| 5 | + |
| 6 | +The Astropy project is made both by and for its users, so we accept contributions of many kinds. |
| 7 | +We always welcome contributors who will abide by the :ref:`astropy-org-coc`. |
| 8 | + |
| 9 | +.. _astropy-org-contribute-feedback: |
| 10 | + |
| 11 | +Contribute feedback |
| 12 | +------------------- |
| 13 | + |
| 14 | +There are several ways in which you can give feedback. |
| 15 | + |
| 16 | +- If you would like to give feedback and participate in discussions, we encourage you to join the `astropy mailing list <http://mail.python.org/mailman/listinfo/astropy>`__ and post there. |
| 17 | + This is the easiest way to have a discussion with both developers and other users. |
| 18 | +- Feature requests from the community are welcome and encouraged. |
| 19 | +- If you have feedback you would prefer to keep private, you can e-mail feedback@astropy.org. |
| 20 | + This address points to a private mailing list that includes the astropy core developers. |
| 21 | + If you would like a reply (e.g., an acknowledgement of your comment), please request it. |
| 22 | +- For the extremely impatient, astropy developers often can be found in the `Astropy Slack team <https://astropy.slack.com>`__ (get an account `here <http://joinslack.astropy.org>`__). |
| 23 | + Slack is basically a live web chat. |
| 24 | +- If you would like to participate in discussions about how the Project is run, please join the `Developer Email List [astropy-dev] <http://groups.google.com/group/astropy-dev>`__. |
| 25 | + |
| 26 | +.. _astropy-org-contribute-issues: |
| 27 | + |
| 28 | +Reporting Issues |
| 29 | +---------------- |
| 30 | + |
| 31 | +If you have found a bug in Astropy please report it. |
| 32 | +The preferred way is to create a new issue on the Astropy `GitHub issue page <http://github.com/astropy/astropy/issues>`__; that requires `creating a free account <https://github.com>`__ on GitHub if you do not have one. |
| 33 | + |
| 34 | +If you prefer not to create a GitHub account, please report the issue to either the `astropy mailing list <https://mail.python.org/mailman/listinfo/astropy>`__, the `astropy-dev mailing list <http://groups.google.com/group/astropy-dev>`__ or sending a private email to the astropy core developers at feedback@astropy.org |
| 35 | + |
| 36 | +Please include an example that demonstrates the issue that will allow the developers to reproduce and fix the problem. |
| 37 | +You may be asked to also provide information about your operating system and a full Python stack trace; the Astropy developers will walk you through obtaining a stack trace if it is necessary. |
| 38 | + |
| 39 | +.. _astropy-org-contribute-code: |
| 40 | + |
| 41 | +Contribute code or documentation |
| 42 | +-------------------------------- |
| 43 | + |
| 44 | +If you are interested in contributing fixes, code or documentation to Astropy (whether the core package or affiliated packages), you should join the `astropy-dev <http://groups.google.com/group/astropy-dev>`__ mailing list/forum. |
| 45 | +For the core, start looking at any related `issues <https://github.com/astropy/astropy/issues>`__. |
| 46 | +In particular, we have introduced a labeling system used across most Astropy-related packages which will allow you to find good starting issues. |
| 47 | +Good labels to start with are `Good-first-issue <https://github.com/astropy/astropy/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22>`__ and `Package-novice <https://github.com/search?p=2&q=label%3Apackage-novice&ref=searchresults&state=open&type=Issues&utf8=%E2%9C%93>`__ which means you don't need much prior experience of the package. |
| 48 | +You can use the following links to find all the issues labeled this way and also labeled by how much work they involve: |
| 49 | + |
| 50 | +- `Effort-low <https://github.com/search?p=2&q=label%3Apackage-novice+label%3Aeffort-low&ref=searchresults&state=open&type=Issues&utf8=%E2%9C%93>`__: issues that should take a few hours at most |
| 51 | +- `Effort-medium <https://github.com/search?p=2&q=label%3Apackage-novice+label%3Aeffort-medium&ref=searchresults&state=open&type=Issues&utf8=%E2%9C%93>`__: issues that should take a few days at most |
| 52 | +- `Effort-high <https://github.com/search?p=2&q=label%3Apackage-novice+label%3Aeffort-high&ref=searchresults&state=open&type=Issues&utf8=%E2%9C%93>`__: longer term issues |
| 53 | + |
| 54 | +You may also want to familiarize yourself with the `developer documentation <https://docs.astropy.org/en/latest/#developer-documentation>`__, particularly the `coding <https://docs.astropy.org/en/latest/development/codeguide.html>`__ and `documentation <https://docs.astropy.org/en/latest/development/docguide.html>`__ guidelines. |
| 55 | + |
| 56 | +Once you have a change to propose, if it's a simple fix to just a single file, you can even just browse to the appropriate file and use the "edit" button on github. |
| 57 | +If it's a more complex change, we suggest you follow the `developer install instructions <https://docs.astropy.org/en/latest/development/quickstart.html#install-the-development-version-of-astropy>`__, and use that with `Astropy's github page <https://github.com/astropy/astropy>`__ to issue a pull request with your changes. |
| 58 | +If you aren't familiar with github, we suggest you looking over our `workflow documentation <http://astropy.readthedocs.org/en/latest/development/workflow/development_workflow.html>`__. |
| 59 | +Once your code is accepted, you are officially an Astropy contributor and eligible to be included on the author list of future publications. |
| 60 | + |
| 61 | +If you want to propose a larger change to Astropy, there's a procedure for that: `Astropy Proposals for Enhancement (APEs) <https://github.com/astropy/astropy-APEs>`__ (modeled after Python's `PEPs <http://legacy.python.org/dev/peps/>`__). |
| 62 | +The sort of changes that APEs are intended for include plans for new sub-packages, wide-ranging code re-organizations, a new procedure needing review by a lot of the Astropy community, or an informational document on some decision for Astropy that you want remembered. |
| 63 | +For more background on APEs, check out `APE #1 <https://github.com/astropy/astropy-APEs/blob/main/APE1.rst>`__ and the `APE repository's README <https://github.com/astropy/astropy-APEs/blob/main/README.rst>`__. |
| 64 | +There is also a `wiki page on Astropy's github repository <https://github.com/astropy/astropy/wiki/APE-Overview>`__ that has an overview of the existing APEs. |
| 65 | + |
| 66 | +.. _astropy-org-contribute-role: |
| 67 | + |
| 68 | +Taking on a formal project role |
| 69 | +------------------------------- |
| 70 | + |
| 71 | +If you are interested in a higher level of contribution to the project, you can consider taking on one of the formal project roles as listed in the :ref:`astropy-org-team` page. |
| 72 | + |
| 73 | +In order to be nominated for a named Astropy role, it is typical that a person will have been actively involved in the project for a considerable amount of time (at least a year and often longer) and have made substantial contributions. |
| 74 | +They will have shown a sustained commitment to Astropy by participating actively already in activities related to the role. |
| 75 | +This could involve submitting pull requests and participating in reviews, or discussions in other channels such as mailing lists or Slack, or other contributions as defined by a particular role. |
| 76 | +Finally, they need to express a desire to maintain this involvement going forward and accept the responsibility of having a role. |
| 77 | +For example, being a core sub-package maintainer involves interacting with users and responding to bug reports in a timely manner. |
| 78 | +If you are interested in taking on such a role, you can volunteer either on `astropy-dev <http://groups.google.com/group/astropy-dev>`__, by talking to a holder of the role you are interested in, or a coordination committee member. |
| 79 | + |
| 80 | +.. _astropy-org-contribute-affiliated: |
| 81 | + |
| 82 | +Develop an affiliated package |
| 83 | +----------------------------- |
| 84 | + |
| 85 | +Whether you have an idea for a new Astronomy package, or already have a package that you want to integrate with the Astropy project, you can develop an affiliated package! You'll want to join the `astropy-dev <http://groups.google.com/group/astropy-dev>`__ list so you can notify other developers of your intent to develop an affiliated package, and the `astropy-affiliated-maintainers <https://groups.google.com/forum/#!forum/astropy-affiliated-maintainers>`__ mailing list to be kept informed of any discussions related to setting up affiliated packages. |
| 86 | +Then you can check out the section on :ref:`astropy-org-affiliated-instructions` to get started. |
| 87 | + |
| 88 | +.. _astropy-org-contribute-financially: |
| 89 | + |
| 90 | +Contribute Financially |
| 91 | +---------------------- |
| 92 | + |
| 93 | +Donations to Astropy are managed by `NumFOCUS <https://numfocus.org/>`__. |
| 94 | +For donors in the United States, your gift is tax-deductible to the extent provided by law. |
| 95 | +As with any donation, you should consult with your tax adviser about your particular tax situation. |
| 96 | +If you would like to donate to astropy, please see the NumFOCUS contribution page for the Astropy Project: |
| 97 | + |
| 98 | +.. button-link:: https://numfocus.org/donate-to-astropy |
| 99 | + |
| 100 | + Donate to Astropy |
| 101 | + |
| 102 | +.. _astropy-org-contribute-justify: |
| 103 | + |
| 104 | +For academics: How to justify your contribution |
| 105 | +----------------------------------------------- |
| 106 | + |
| 107 | +While in some more technical areas, contributing code is recognized as a goal in and of itself, some academic fields have not yet developed a clear understanding of the role of code development relative to other more traditional contributions like publication. |
| 108 | +This section aims to provide suggestions to academics for how you might justify contributions to the Astropy project if you are in a field or institution that needs convincing of the value of such contributions. |
| 109 | + |
| 110 | +Contributing to the Astropy Project as a volunteer directly benefits the astronomical research community in tangible ways. |
| 111 | +Nevertheless, people employed in academic departments may be asked to justify their time and efforts in terms of direct benefit to their own department or organization. |
| 112 | +In this case it is worth highlighting the well-established role of community service in academia, including: |
| 113 | + |
| 114 | +- Referring journal papers |
| 115 | +- Reviewing proposals for funding or for an observatory time allocation committee |
| 116 | +- Serving on a conference science organizing committee |
| 117 | +- Serving on an external review committee such as the NASA Senior Review |
| 118 | + |
| 119 | +These volunteer duties typically bring no direct benefit to the home department of a researcher, yet they are widely accepted as necessary to the functioning of global research astronomy. |
| 120 | +We should now add the following to the above list of community service duties: |
| 121 | + |
| 122 | +- Contribute to open source software projects that benefit astronomical research |
0 commit comments