astropy / astropy-project

Documents and policies regarding the Astropy Project as a whole.

Astropy

The Astropy Project (https://astropy.org/) is a community effort to develop a single core package for Astronomy in Python and foster interoperability between Python astronomy packages. This repository contains the core package which is intended to contain much of the core functionality and some common tools needed for performing astronomy and astrophysics with Python.

Table of Contents

• Installation
• Contributing
• Getting Started with GitHub Codespaces
• Supporting the Project
• License

Installation

Releases are registered on PyPI, and development is occurring at the project's GitHub page.

For detailed installation instructions, see the online documentation or docs/install.rst in this source distribution.

To install astropy from PyPI, use:

pip install astropy

Contributing

The Astropy Project is made both by and for its users, so we welcome and encourage contributions of many kinds. Our goal is to keep this a positive, inclusive, successful, and growing community by abiding with the Astropy Community Code of Conduct.

More detailed information on contributing to the project or submitting feedback can be found on the contributions page. A summary of contribution guidelines can also be used as a quick reference when you are ready to start writing or validating code for submission.

Getting Started with GitHub Codespaces

Codespaces is a cloud development environment supported by GitHub. None of the Astropy build machinery depends on it, but it is a convenient way to quickly get started doing development on Astropy.

To get started, create a codespace for this repository by clicking this:

A codespace will open in a web-based version of Visual Studio Code. The dev container is fully configured with software needed for this project. For help, see the GitHub Codespaces Support page.

Note: Dev containers is an open spec which is supported by GitHub Codespaces and other tools.

Supporting the Project

The Astropy Project is sponsored by NumFOCUS, a 501(c)(3) nonprofit in the United States. You can donate to the project by using the link above, and this donation will support our mission to promote sustainable, high-level code base for the astronomy community, open code development, educational materials, and reproducible scientific research.

License

Astropy is licensed under a 3-clause BSD style license - see the LICENSE.rst file.

astropy-project's Issues

Governance policies we need to write

We need someone who can take our bullet points and discussions of our "policies" and turn them into actual documents. Leah (NumFocus) has someone internally (Nicole), who she will see if is available and interested in helping us out with this. You could imagine that any documents we write could be used by other projects so this would be an excellent investment in the "full stack" infrastructure.

Figure out how to keep updated the astropy-core-maintainers list

Pey-Lian pointed out this issue in an email. The maintainers list is quite stale.

Obviously for now we should just keep this up-to-date, but moving forward we need someone who's job is to keep this in sync, or some automated way to do it. 🤖

Have a Become a Contributor workshop at the CfA

• Pitch: Ever wanted to edit the astropy documentation or add a small feature? Let’s empower you.
• Maybe email CfA and astropy-users. And astropy-dev to circulate accordingly.
• Target numbers can be small (<10), doesn’t need to be big
• future locations: Cambridge, Baltimore, NYC, Michigan, Seattle.
• FUNDING? CfA Library has funding.
• Kelle will ask at NumFocus sustainability conference about funding.

Draft Scopes of Work (SOW)

For every person we bring on an as independent contractor, we'll need to make a scope of work. These should be detailed but not too detailed.

Proposal: strive to be a carbon-neutral project

This is an idea that was discussed in Socorro (the 2019 Coordination Meeting) and started out from whether we want to scale back our CI builds to reduce our carbon footprint.

The suggestion we came up with is that regardless of whether or not we scale back the CI, we could consider trying to offset project specific CO2-emissions, such as for travel of project members to conferences or meetings, or also the CI itself. It would be good to figure out what kind of costs we'd be looking at, and also we would need to make sure that any carbon offsetting project we use is actually beneficial. If the costs are reasonable, we could aim to be a 'carbon-neutral open source project'!

Just an idea for discussion and investigation at this stage.

Figure out Contract Language for Independent Contractors

Leah (NumFocus) will send us their most generic contract. We should look it over and be sure we're happy with it.

Establish a formal Advisory Board

Work on translation of docs

How can we get our docs translated?

Related issues: astropy/#8618, astropy/#7178. We've also gotten emails about Chinese.

@bsipocz, can you post here about the numpy effort you mentioned?

Better plan presence/talks at conferences

We should make sure we plan our presence at relevant conferences, etc.

find maintainer + deputy for astropy.wcs

Make Profiles of Leads

How did you become involved?
Why do you stay?
How do you get compensated?
What do you like the most?
WHERE TO PUBLISH?

Lynn (Numfocus) will look into overhead rate for subawards

Can we pay full overhead on subawards (e.g., to UW or Hunter) from the Moore funding or are we limited to the 10-15% required by Moore.

Run a user survey

At the NumFOCUS summit, we discussed the merits of running a short user survey to gather general information about user experience. For example, both dask and pandas have recently run such surveys.

We have run surveys (either via google form or by mailing list post) in the past, but recently these have been for very specific goals (assessing performance, python 2 to 3, etc.). Others have also run more general surveys of the astronomical community about, e.g., software use.

This issue is meant to start a discussion about whether we think it would be useful to run a similar survey. However, I think we should mainly discuss this face-to-face at the coordination meeting, and this issue should just serve as a place to remind us and collect broader feedback.

This is all open for discussion, but I was imagining a short (~5 min), information-gathering survey to assess how users use and perceive the astropy core package. For example, what operating systems they use, how they learn to use astropy, etc. To clarify, I'm not suggesting that we solicit general feedback about the package, but rather to gather more general statistics.

Goals of a survey

I've included here a few goals for running such a survey, but please suggest modifications or additions.

• Gather statistics about the systems, computers, and environments in which people are using astropy
• Gather some very basic demographic statistics, e.g., at least country of residence/work, position (academic, industry, etc.),
• Gather statistics about what subpackages our users use the most, and what other packages are being used with astropy most frequently
• Gather information about points of entry to astropy
• Gather information about what educational materials people use, attendance to conferences (e.g., PyAstro, AstroHackWeek, AAS hack day, etc.)
• Gather information about perceptions of the developer community
• Understand whether our users know how to (if they want/need to): report a bug, get help/support, contribute code

Open threads

• We should discuss or coordinate with NumFOCUS on how to review the questions. For example, is there a social scientist we can pay to consult on this?
• If we want to publish results (in a journal, e.g., BAAS), do we need IRB approval?
• Do we want to borrow questions from the Python developers survey to compare / benchmark against the broader Python community? Is that useful?

Discuss!

Make a new "Unacceptable Behaviors" Document

So it turns out our Code of Conduct includes some aspirational elements which are more like "desirable" behaviors rather than "unacceptable behaviors." We might want to consider having a 2nd document which outlines the most egregious Code of Conduct violations. I propose this document could be called "unacceptable behaviors."

Formalize new feature freeze guidelines

At the 2018 coordination meeting we discussed how to rename/reorganize the feature freeze so that we don't have all PRs opened a few days before the actual branching. We should figure out where this should be written down.

Add license

CC-BY or BSD?

Promote slack channel

• joinslack.astropy.org

invite sent to [email protected]

Let's populate a bit and then invite astropy-dev, eventually astropy and maybe Python FB group.

Also wait to see how many folks we get to ask about upgrading and getting video chat feature (could be really useful for screen sharing).

Affiliate e-mail addresses

I wonder whether it would make sense to create e-mail addressed under astropy.org for the affiliated packages, that can be then forwarded to the maintainers? Some already do this, but with gmail addresses (e.g. [email protected]), but it would be much nicer to have the [email protected] alias.

checklist for maintainers

@eteq recently added me as a maintainer to help with the stats package and I was wondering if there was a checklist of things that should be confirmed before accepting a pull request?

Although I do see this page:
http://docs.astropy.org/en/latest/development/workflow/maintainer_workflow.html
as well as another useful page (which I can't seem to find right now with a description of the code, testing, documentation, and change log)

I'd be happy to start putting a list together of things that should be checked and starting a pull request but obviously the people who have been doing this for awhile probably have a good idea what should be in the list.

cc: @astrofrog @embray

Subscriptions to start paying for

Once we get our own credit card, what should we buy?!?

• Slack [Update: we now have upgraded Slack via NumFocus.]

Anything else?

Google Analytics Comparison

Find out what other sites we could compare our analytics to. E.g., Astropy vs. Astrobetter. Maybe other docs sites (jwst docs, lsst docs?) cc @astrofrog

How to find contractors

Do we want to use Fiverr or Something similar to find folks to do website and other non-Astro specific things.

Invoicing workflow

Currently, independent contractors have to upload PDF invoices via Rocket in order to get paid. NumFocus (Leah & Lynn) will work on either making an invoice template, or better yet, a form on Rocket which folks can use to submit the info rather than making an actual invoice.

Setup pep8speaks comments

As decided at the Coordination meeting, one of us (not me!) needs to setup pep8speaks. Any takers?

Go through ADASS BoF document and make sure we extract all actionable item

I can do this, but this is just a reminder to do so, and others are welcome to help:

https://docs.google.com/document/d/1nbnE5CiQhhG43cd1Kq6IfHiUSuVxf8O8-HnD1fWJTxM/edit#

Code Review Checklist

Do we have a code review checklist? If not, I think we should. Maybe we could just crowdsource this by starting a discussion on astropy-dev asking people what they think should go on the list?

Relevant articles which I skimmed:

• http://blog.smartbear.com/code-review/creating-your-code-review-checklist/
• https://blog.fogcreek.com/increase-defect-detection-with-our-code-review-checklist-example/

Recognize previous roles

Somewhere (doesn't have to be too obvious necessarily) we should keep a list of people who were previously in roles, so that there is an official place we record this (because I think we should recognize past as well as current contributions)

Move GSOC money to SunPy

Since we have the Moore money now, we discussed it with Stuart and it makes sense to move the GSOC money (from Open Astronomy) into the SunPy account.

I don't think we need to take any action, but FYI.

Andy (Numfocus) will look into lawyer to help us with contracts

We need some help looking over current contracts and requesting modifications to current contracts to allow support from Moore funding.

look into offering @astropy.org email addresses to contributors

Consider using this repository for other project-wide policies and issues

Rather than use this repository just for community engagement issues, we could rename it to something more general and to keep track of many project-wide issues, including many of those discussed at in-person coordination meetings. The repository itself could include documents with processes and policies, and new policies could be suggested either as issues or (better) pull requests.

DOC: Clarify what issues go to which repo

At the time of writing, https://github.com/astropy has 76 repositories. It is getting confusing what issue should go where. There needs to be a page to clarify this somewhere (website?).

For example: What if I want to nominate/promote a new maintainer? Do I open PR over on team website repo? Or write something here?

Investigate outreachy

Someone on the Jupyter project recommended https://www.outreachy.org/ as a way to get competent interns (not just students)

PEX cards?

How many should we get and who should get them?

Start paying folks who are currently in roles

Folks who are currently in roles should be first in line to start getting paid. Let's get the wheels turning using this group. How does this work? Who keeps track? Us or NumFocus? Does NumFocus want to receive this information in a particular format?

Policy for copy editing - push access required

From APW:

We wrote up a policy for copy editing:

When a pull request is feature-complete and has touched the documentation:
Maintainer assesses whether the docs change is “substantial” and requires copy-editing (i.e. single-character changes or fixes generally don’t require copy-editing)
Add “needs-copyedit” label
Request review from @lglattly
@lglattly reviews pull request:
If a small number of changes required, submit as requested changes
If many changes required, push changes directly to author’s branch
Both of these require a subsequent review from @adrn to verify changes
When copy-editing is complete, @lglattly removes “needs-copyedit” label, adds “copyedited” label
Copy-editing should not be a long blocker for merging, so if a PR is merged with “needs-copyedit” it can be found later and acted upon (if necessary)

Right now, the point 4.2 "If many changes required, push changes directly to author’s branch" is needed because GitHub can't handle committing a large batch of suggested changes. Also, maintainers can't accept and commit the changes as a batch. However, I believe the only way to enable Lauren push to another users branch would be if we give her write access.

Do you have any ideas or thoughts here?

Thanks!

• Adrian

Hire a person to help with PRs, especially first time contributions

We can hire a person to help improving the contribution process.

• respond to new PRs within 24 hours
• help with technical hoops (e.g., rebase, squash, tests, etc)
• work on establishing and/or polishing guidelines for contribution process

Consider deferred compensation?

For those that cant earn as part of their current contracts, maybe they accumulate hours, and we pay them at a later date? Can we do that?

Internationalization/Translation of docs

How to translate the docs? This is a very tough problem.

Consider using All Contributors.org to keep track of contributors

Way to keep track of who is doing what. https://allcontributors.org/docs/en/overview

It's a bot which keeps track of the nature of all contributions. Check out the emoji table, in particular: https://allcontributors.org/docs/en/emoji-key

Relevant to astropy/coordination#84

MNT: Clean up stale branches in this repo

I forked this repo and inherited a bunch of stale branches. Would be nice to clean those up.

Need new role: Triage team

need Triage Team (or First Responder Team) to recognize the work with Brigitta and Pey Lian do like on issues and PRs. This team could potentially include the new role identified in astropy/coordination#159 to help with making sure first response to issues and PRs is welcoming and timely.

What's our travel reimbursement policy?

• Economy class + up to $50 for seat selection. If more expensive cabin is purchased, please provide the cost of the economy fare on the same flight and that's what will be reimbursed.
• ok to pay more for direct flights.
• no booze.
• up to GSA per diem rate, no meal receipts but please request as close to actual costs as possible.
• every effort should be made to purchase flights at least 30 days in advance of travel.

astropy.cosmology needs maintainers

develop mentoring program

broadening participation.

Demographics of contributors

It would be great to have at least the city/country in which our top ~50 contributors are based. I feel like this could be done quickly/easily from the github profiles? (@bsipocz @sosey?) Maybe we send an email to dev asking folks to update their profile. (A larger demographic survey is being led by NumFocus and is in the fund raising stage.) btw, this was motivated by a user asking to be connected to folks who are based in Australia.

GitLab backup plan

Mirror GitHub code, issues, and pull requests, where possible, to GitLab. This is to reduce the risk of single point of failure in terms of project hosting.

As brought up during Astropy Coordination Meeting 2019.

Establish a formal users group

annual prizes and/or awards

We should have prizes and/or awards every year. They can be different for every person depending on their effort level. E.g., a new hoodie for most folks but customized things for ~5 folks reaching some kind of milestone (e.g., 10 year contributor, most valuable player).

(We could do this as soon as Python in Astro in the Spring.)

@taldcroft: Please put some example milestones and prizes you think would be good.

Consider doing a transparency report

We could do an annual report of the Code of Conduct violations and other matters related to the community. See example here from PyCon:
https://pycon.blogspot.com/2018/06/pycon-2018-code-of-conduct-transparency.html