OpenWorm Community
This page contains information intended to help individuals understand what steps to take to make contributions to OpenWorm, how to join OpenWorm meetings, how to interact with the community online, and how to become an OpenWorm core member.
An Opening Note
Feeling lost? Not uncommon in open source projects. In fact, there are whole papers describing the kinds of problems you may be having and some proposed solutions. Help us make helping you easier by reaching out to us to ask for help on the mailing list. See below for additional information on our repo specific chatrooms.
Contribution Best Practices
What do I work on? We outline the work we are doing in the project using GitHub issues. Therefore, in order to figure out what to help out on, you need to be able to check them out for yourself. One way is to use this documentation to find a project you want to contribute to.
Find tasks to work on
Another way is you can browse the top-level board of issues directly.
Other key boards:
Come chat with us!
You can initiate a conversation with us on our chatrooms to get more specific about issues.. Currently these are:
Once you have identified an issue you want to work on from a particular project, please announce your intention to help out by commenting on the specific GitHub issue.
Using OpenWorm repos on GitHub
Making a contribution of code to the project will first involve forking one of our repositories, making changes, committing them, creating a pull request back to the original repo, and then updating the appropriate part of documentation.
An alternate way to contribute is to create a new GitHub repo yourself and begin tackling some issue directly there. We can then fork your repo back into the OpenWorm organization at a later point in order to bring other contributors along to help you.
More details on best practices using OpenWorm repos on GitHub are available on a separate page.
Creating organizing documents
Another great way to contribute is by organizing ideas or documentation or proposals via a Google doc, and then sharing the link on our mailing list.
To contribute documentation and materials to the OpenWorm Google Drive, log into your Gmail account and click on this link.
All documents located in the OpenWorm folder is viewable to the public. Comments can be added to both text documents and spreadsheets. In order to edit existing documents or to add a new document, you will need to be added to the folder. You can request access by email your Google ID to info@openworm.org.
Taking notes as Google docs
It is very useful to create notes and progress reports as the result of meetings as Google docs. Docs should be shared publicly with view and comment access.
An effective progress report should contain the following information:
- Meeting title
- Attendees
- Date
- Goal being worked on (link back to doc page describing project)
- Previous accomplishments
- Recent progress towards goal
- Next Steps
- Future Steps
An example of an effective progress report is available online.
Once the document is shared, it should be announced on the mailing list.
Creating proposals as Google docs
To gather public comment on a direction for the project, it is often effective to create a proposal as a world-editable Google Doc. Once your document is created and shared, it should be announced on the mailing list.
An example of an effective proposal is available online
Contributing to the OpenWorm documentation
The OpenWorm documentation is a searchable repository of knowledge we have assembled to help new users get oriented to the different areas of the project. When new contributions are made, it is important that they are incorporated into the appropriate part of the documentation.
When they are ready to consume by the general public, simulation engines, visualization environments, and data sets should be added to the resources page.
Information about the goals, progress, and roadmap of current or proposed projects should be added to the projects page.
The docs use "Github-flavored" markdown format. This makes writing for Github (where most of our code is stored) and writing the documentation seamless. Markdown is also more forgiving in its syntax than, say, ReSTructured text, which was used previously.
The documentation is published on the ReadTheDocs service, which helps it remain searchable and beautiful.
The markdown documentation is rendered using the Python module MkDocs, making theming and structuring much easier. The outline of the Table of Contents tree is structured in mkdocs.yml.
Changes that appear in GitHub will automatically trigger a hook that will cause the documentation on ReadTheDocs to become rebuilt and pushed onto the site. There are different versions of the documentation that are explained below.
OpenWorm Documentation Versions
Multiple versions of the documentation are enabled via GitHub branches. The content that appears as 'latest' online corresponds to what is in the master branch in the repo. This content should be dynamic and a space for adding stuff boldly.
The content that appears as a numbered version, like 0.5 corresponds to what is in the branch named 0.5 in the repo. This content should be considered stable and not updated lightly.
Keeping a division between latest and the versioned documentation is important for several reasons:
- Latest acts as a staging area - We don't want errors exposed to the public, so having an extra layer of review by checking the page on latest first is valuable.
- URL Stability - content in latest is easy to update. Pages can be moved or deleted easily, breaking URLs that we have given out. If we make sure not to move pages around on the versioned docs, we can sustain URLs.
- Versions should correspond to major releases of the project as a whole, which happen approximately every six months. As the project naturally evolves, the versioned docs provide a motivation for the entire documentation to be re-evaluated as a whole.
The recommended best practice when updating the documentation is that if your changes fix bugs with the documentation that don't involve moving pages, renaming pages, or deleting pages, then check them in first to latest. Then on a regular basis the changes can be evaluated to be back applied to the most recent version. If your changes add new projects or new content, or update a documentation page with the results of new events, keep this in latest and it will get rolled into the next version.
Guest Blog Post
We love hearing about what members are of the OpenWorm community are doing. If you have something to share, contact us at info@openworm.org to discuss.
Journal Clubs
Every few months an academic journal article comes along we can't resist talking about. We host a journal club where we invite scientists to present on the paper and to host a discussion about it, hopefully with some of the article authors.
You can see past journal clubs we have conducted online.
If you have an idea for a good journal club, please post the suggestion on our mailing list.
Coding Standards
It is recommended to follow the PEP8 Guidelines. For contributions of Python code to OpenWorm repositories. Compliance can be checked with the pep8 tool and autopep8
Meetings
Team meetings
We have a regular meeting of the team that is building applications every month.
We also have a regular Movement Validation team meeting once a month.
We also currently schedule an ad-hoc Muscle / Neuron team meeting about every 3-4 weeks. The events are on our community calendar. The events are streamed live when they occur and an archive of the meeting videos and the minutes are kept online.
Working meetings
Contributors are encouraged to meet with each other on a regular basis to advance areas of the project they need interaction on.
Chatroom for OpenWorm
We have a new chatroom on Gitter. Check it out!
Scheduling meetings
We like using the Doodle service for scheduling meetings. This makes it easy to find times to meet across various time zones. Once a meeting is scheduled, we will often create a Google+ event to track it and remind everyone it is occurring.
Interactions
Mailing Lists
There are two Google Groups in connection with OpenWorm. We suggest joining both lists to stay current, introduce yourself to the project, and participate in ongoing discussions. Simply login with you Gmail username and click on "Join Group" for each list.
This list is for general updates and announcements related to the project.
This list is for high-volume type technical discussions, day-to-day communications, and questions related to the OpenWorm project.
Google Plus
Click on the "Follow" button to be a part of the OpenWorm community on Google+.
If you need more help with Google+, check out the handy guide put out by Google.
YouTube
Want to get notified when new content goes live? Subscribe to the channel by clicking on the "subscribe" button while logged in to your Google account.
Playlists
- Status Updates - Biweekly updates from the OpenWorm team.
- Journal Clubs - Like journal clubs that meet in person, the OpenWorm journal clubs use discuss new discoveries, tools and resources related to neuroscience, C. elegans, computational biology and open source science. Journal clubs are posted to social media in advance for any to watch and recordings then become available on YouTube. Learn more about our journal clubs.
- Data Team meetings - Learn more about our team meetings.
- Real C. elegans
- Building Blocks
Want to tag OpenWorm on a tweet? Use @openworm and share the love.
Blog
Our blog is hosted in Tumblr.
Interesting in being a guest on our blog? We love hearing about what members of the OpenWorm community are doing. If you have something to share, contact us at info@openworm.org to discuss.
Membership
More information about the membership policy is available on a separate page.
Use of OpenWorm logo
The OpenWorm logo font is Kefa.
This is the OpenWorm logo:
Click here for a vector version of the logo. All three layers are vector.
It may be adapted for subteams. Please follow these style rules when doing so:
- Don't apply effects (e.g. shadows) to the text; use flat style
- If any icon is added it should be flat looking and its colour should be #92bd1e
- Do not use detailed/real looking graphics
- Keep it simple
- Do not alter the OpenWorm logo itself
- Logo needs to be readable when rendered in grayscale
Such logos are subject to review by the core team to retain consistency across the project.