diff --git a/source/ARTICLE.md b/source/ARTICLE.md index fb424e7..5e8f1c4 100644 --- a/source/ARTICLE.md +++ b/source/ARTICLE.md @@ -1,134 +1,94 @@ -# Brainhack Paper Guideline - -Here you are provided a quick guideline to help you addressing the scientific question and the research is done in your paper in a well and simply formatted way. - -Not all of the items listed here are the absolute requisities to pass the review processes but they are important points to take into consideration for including in your paper for the clarity and sanity of the research conveyed and to make it easy to be understood by the public. - -So please use this guideline as a matter of checklist regarding your preprint. +# Paper Guidelines +Here are guidelines to help you format your paper in an effective way. Some items are mandatory, while others are suggestions to help with the clarity and accessibility of the text. We recommend proceedings to **remain under four pages**, and shorter submissions are welcome. Exceptions can be granted by the editors if necessary (project with large scope running over multiple hackathons, for example). ## Project Information -### Title (required) - Provide the working title of your project. It may be the same title that you submit for publication of your final manuscript, but it is not a requirement. - -**Extra info:** The title should be a specific and informative description of a project. Vague titles such as “Brainhack preprint plan” are not appropriate. +### Title (required) +Provide the working title of your project. The title should be a specific and informative description of the project. -## Authors (required) -List all the project attendees that are associated with any part of the project run from the first day of the Brainhack until the latest day of the registration. +## Authors (required) +List all the project attendees that are associated with any part of the project, provided these individuals agree to be listed as co-authors. A list of contributions is included at the end of the paper. ## Abstract (required) -- Please give a brief description of your study, including some background, the purpose of the study, or broad research questions. -- If the project is based on a study, please clearly declare the hypothesis. -- Give the open-access link (Git-based repository, OSF preprint) of the repository where the tool developed and the material produced associated with the project. - - -**Extra info:** The description should be no longer than the length of a short paragraph. It can give some context for the proposed project, but great detail is not needed here for your preprint. +The abstract should be less than 200 words. +- Please give a brief description of your project, starting with some background and the main objective. +- Summarize the main methods and results. +- Give the links (e.g. Github repository, OSF preprint, zenodo data) for the outcomes of the project. +- Explain how the outcome of the project can benefit the broader community. ## Keywords (required) Indicate the keywords related to the project ## Introduction (required) -- Give a brief literature review based on the work that has been done in the field. -- List specific and concise aims and necessities of the project; in other words, the fulfilled milestones pre-specified in your project pitch aiming for a diverseaiming diverse and non-specialist audience. -- Give an overview of the work that has been done throughout the project. -- Indicate how the project would benefit the neuroscience society (i.e. implications of the project). -- Give a link to the open platform(s) where the project materials is (are) listed and stored along with the explanation of how they can be accessed. - - +- State the main overall context and objective of the project. +- Give a brief literature review based on the work that has been done in the field relevant to that objective. +- List specific and concise aims of the project. For brainhack projects, these objectives will be similar to the project description posted on [brainhack.org](https://brainhack.org). +- Give a brief summary of the work that has been done throughout the project. ## Methods -- Software Tool Development Based Projects. -- Explain how/which way already existing tools/hardware are employed in the development of the project. -- List the details of the specific functionalities of the developed tool. -- Explain how this tool can facilitate user experiences. -- Please indicate all the necessary cross-references (e.g. using the format of [dataset] Authors; Year; Dataset title; Data repository or archive; Version (if any); Persistent identifier (e.g. DOI) or the publisher’s format) to reference the data used in your project. If you had to create or acquire a new dataset for your project, please make it publicly and openly available, and provide a means so that it can be cross-referenced. -- Explain the reason for the choice of the data, what the data includes, from which repository (provide URL, identifier or accession code to help others to access the data for reproducibility purposes) and indicate the related taken permissions and ethics applies to the data. If the data is a restricted use only and you have specific permissions to use, please indicate the legal and ethical reason for the restriction, and provide a link to the organization/group/publication the data is taken from. -- In some cases the publisher of the data might not be willing to accept the citation to the data, in such cases cite the publication/paper that uses and explains the data, its collection etc. -- In case you use existing data to test the tool, please describe and explain the steps you have taken to assure that you are unaware of any patterns or summary statistics in the data. This may include an explanation of how access to the data has been limited, who has observed the data, or how you have avoided observing any analysis of the specific data you will use in your study. -- Indicate every processing applied to the data (e.g. preprocessing, dimensionality reduction, thresholding, etc.). -- If you will collect a new data set to test and/or validate the tool, please adhere to section 5.3. - -### Guideline/Workflow Development Based Projects -- Indicate the purpose of the to-be-achieved guideline/workflow. -- Specify the target community and describe to which pipeline or the tool will contribute and how it will facilitate the use of that pipeline. -- Address how this tool will be helpful to the target community. -- Describe the plan for dissemination of the use of the tool by the widespread communities. -### Study Based Projects -- Please indicate your hypothesis regarding the study. +### Data +- Describe which data (if any) was used in the project. - If the study involves human/non-human subjects indicate the related ethics application details. -- If the study involves human subjects explain how the subjects were informed about the study details and their consent are taken. -- If the study involves human subjects indicate how the subject data will be secured and stored. -- Explain the study design including the groups and measures (repeated, factorial, two-group, randomized). Is it a between (unpaired, paired), within-subject (paired), or mixed design? Describe any counterbalancing required. Typical study designs for observation studies include cohort, cross-sectional, and case-control studies. -- Example: We have a within-subject design, with one-factor accuracy (two levels: accurately cued / inaccurately cued trials). - -**More info:** This question has a variety of possible answers. The key is for a researcher to be as detailed as is necessary given the specifics of their design. Be careful to determine if every parameter has been specified in the description of the study design. There may be some overlap between this question and the following questions. That is OK, as long as sufficient detail is given in one of the areas to provide all of the requested information. For example, if the study design describes a complete factorial, 2x3 design and the treatments and levels are specified previously, you do not have to repeat that information. +- If the study involves human subjects explain how the subjects were informed about the study details and their consent are taken, and how the subject data will be secured and stored. +- Datasets should ideally be referenced as citations, including DOI. +- If you had to create data for your project, please make it publicly and openly available on an established platform such as [zenodo](https://zenodo.org/), [figshare](https://figshare.com/) or [OSF](https://osf.io/). +- Motivate the choice of the dataset, as well as possible access restrictions (e.g. data access committee), and cite relevant references describing the data. +- Indicate every processing applied to the data (e.g. preprocessing, dimensionality reduction, thresholding, etc.). -- Please describe the process by which you will collect your data. If you are using human subjects, this should include the population from which you obtain subjects, recruitment efforts, payment for participation, how subjects will be selected for eligibility from the initial pool (e.g. inclusion and exclusion rules), and data collection timeline. +### Software Development +- Explain which tools/hardware are employed in the project. +- Reference the different issues which were created to address the objectives of the project. +- Explain which testing procedures have been implemented. + +### Guidelines/Workflow or educational resources/event +- Specify the target community for the resources. +- Specify how you assessed the utility of proposed resources for the target community. +- Describe the support resources for the proposed resources (documentation, website) +- Describe the plan for dissemination of the resources in the target community. +- Describe the plan for measuring the engagement and effectiveness of the resources in the target community. + +### Data analysis +- Explain the study design including the groups and measures. +- Please describe the process by which you will collect your data. - Justify and identify the sample size of your study. How many units will be analyzed in the study? -- Describe each variable that you will measure. +- Describe each variable that you will measure. - Please list all the basic steps of your preprocessing. - Please briefly explain how the preprocessing of the data will be held? (methods, tools, pipeline etc.) -- Please briefly explain how you will analyze the data. +- Please briefly explain how you will analyze the data. - What statistical model will you use to test each hypothesis? -- How will you determine what data or samples, if any, to exclude from your analyses? How will outliers be handled? Will you use any awareness check? Is there a minimum number of trials participants should contribute to the analysis? +- How will you determine what data or samples, if any, to exclude from your analyses? - How will you deal with incomplete or missing data? -## Progress (required) -- The process completed before Brainhack -Explain the work has been completed before the hacking. - -- The process completed throughout Brainhack -Explain the work has been completed during the hacking period. - -- The process completed after Brainhack -Explain the work has been completed during the hacking period. +### Educational resources or event +- Specify the target community for the educational resource/event. +- Specify how you assessed the utility of proposed educational resources/event for the target community. +- Describe the support resources for the proposed educational resources/event (documentation, website) +- Describe the plan for dissemination of the educational resources/event in the target community. +- Describe the plan for measuring the engagement and effectiveness of the educational resources/event in the target community. ## Results (required) -- Explain the main results of the project/collaborative work. -- Include figures that would help with the explanation of the tool developed. +- Outline the stages of the project, prior, during and after brainhack. +- Explain the main outcomes of the project. +- Include one or two figures to summarize the results and/or the methods. -## Implications and Future Directions -- List the implications the project comes with the current version with the main reasons behind them. -- List the ideas regarding the solutions towards overcoming the implications. -- List the future directions and plans regarding the tool developed and how these future plans are aimed to be achieved. +## Conclusion and Future Directions (required) +- Summarize the outcomes of the project. +- Highlight the benefits of the project for the wider open neuroscience community. +- List the future directions and plans, and how this project can contribute to wider, long-term efforts. -## Conclusion -- Summarise the aim of the project and the achieved success/work done by the submission of the registration form. -- Highlight the main facilitation the tool brings to the neuroscience and open science community. ## Acknowledgment - Indicate the additional information regarding the contributions outside the project attendees. If any of the instructors provided the necessary guidance for the project to be successful and is not listed in the authors, acknowledge them. +- List the funding, data or other resources that supported the project. -## Ethics and Security -###Collected Data -- Indicate the ethics application/process regarding the data collection processes. -- Indicate how the data collected will be stored in a safe and secure way. -- Indicate under which agreement data sharing is agreed and approved across the parties attended to the development of the project. - -### Existing Data -- Briefly describe where the data is obtained. -- Briefly describe how the data has been collected. -- Briefly describe how the data has been anonymized. - -## Author Contributions -- List the author’s initials and their contributions to the project. This section is for the identification of the specific role(s) of the authors throughout the project. +## Author Contributions (Required) +- List the author’s initials and their contributions to the project. This section is for the identification of the specific role(s) of the authors throughout the project. We suggest you follow the `all-contributors` [specifications](https://allcontributors.org/docs/en/emoji-key) for contributions. ## Conflict of Interest -- Declare whether there is any conflict of interest with the authors and the project. -Acknowledgement -- Indicate/list the funding, grants, data or resources that were provided by a third party company/funding agency/research body that facilitated and supported the proposed study. +- Declare whether there is any conflict of interest with the authors and the project. If none is present, state `The authors report no potential for real or perceived conflict of interest for the present project.` ## References -- List the references used in the preprint. +- List of references. ## Appendix/Notes -- Any additional documentation, supporting materials that has to be listed with the publications or needs to be addressed for further details that is stored in the repository should be listed with their direct links in this appendix section. - - - - - - - - - +- Any additional documentation, supporting materials. diff --git a/source/AUTHORS.md b/source/AUTHORS.md index c0889eb..0d091ae 100644 --- a/source/AUTHORS.md +++ b/source/AUTHORS.md @@ -1,16 +1,26 @@ -# How to submit to Brainhack Proceedings +# How to submit ## Submission guidelines for authors. -To create a paper for your project, simply follow the instructions in the [Brainhack Proceedings template](https://github.com/brainhack-proceedings/template). It will take you through all the steps up to the submission based on a rich template that you can easily adapt to the needs of your paper. -Once your paper is ready, you can submit it by [creating an issue](https://github.com/brainhack-proceedings/submit/issues/new?assignees=&labels=HOPE+Object+Submission&template=hope-object-issue-template.md&title=) in this repository, using the "Submission" template, and fill in all the information. +To create a paper for your project, follow the instructions in the [Brainhack Proceedings template](https://github.com/brainhack-proceedings/template) as well as our guidelines for filling the different sections. The template documentation will take you through all the steps up to the submission based on a rich template that you can easily adapt to the needs of your paper. +Once your paper is ready, you can follow the following steps: + +## How to submit? + + - Create a public account on [GitHub](https://github.com/). + - Go to [Brainhack Proceedings Template repository](https://github.com/brainhack-proceedings/template). + - Follow the instructions given in the repository [README](https://github.com/brainhack-proceedings/template/blob/master/README.md) + to create a copy of the template repository at your own local, and edit as necessary. + - [Create an issue](https://github.com/brainhack-proceedings/submit/issues/new) in this repository, using the "Submission" template, and fill in all the information. - Our team will fork your repository on `https://github.com/brainhack-proceedings/your_paper_id`. - We will configure a new github page, and make the paper information and pdf available on `https://brainhack-proceedings.github.io/your_paper_id`. The page will be refreshed every time a new version of the paper is released (revision1, revision2, etc). - A review issue will be opened on the fork, inviting some reviewers. - - Reviewers will create issues. You will need to submit pull requests to address these issues. The editor will close each issue after reviewing they have been properly addressed. + - Reviewers will create issues. You will need to submit pull requests to address these issues. + - The editor will close each review issue after reviewing they advised was properly addressed. - After all issues have been addressed, a "publish" release will be made by the editor. - All versions of the paper will be posted on [https://brainhack-proceedings.github.io](https://brainhack-proceedings.github.io) right after the initial submission. - + - Make sure that you archive your repository in [Zenodo](https://guides.github.com/activities/citable-code/)or [Figshare](https://mozillascience.github.io/code-research-object/) together with your submission to Brainhack Proceedings. Doing so, you will get a Digital Object Identifier (DOI) for your repository while providing a time-free representation to your paper and associated code repositories. + ## Who are the Authors? - Authors are considered as any active local or remote contributors to the project at the time of the project developed and finalised, who had a substantial contribution to the project, not only during the time of the project development taken place for a limited time of the Brainhack but until the project has been finalised or came to a stage to publish the results. @@ -19,9 +29,9 @@ Once your paper is ready, you can submit it by [creating an issue](https://githu - The co-authors' consent to be listed should be taken before they are administrated as the co-authors with the publication. -- The consent should guarantee of the co-authors should be ready to take the responsibilities regarding the any queries and support for the publication. +- The consent should guarantee of the co-authors should be ready to take the responsibilities regarding the any queries and support for the publication. -- Purely financial contributors should not be considered as co-authors but considered as funding supports and needs to be acknowledged at the Acknowledgement section of the paper as necessary. +- Purely financial contributors should not be considered as co-authors but considered as funding supports and needs to be acknowledged at the Acknowledgement section of the paper as necessary. ## Scope @@ -30,36 +40,19 @@ Brainhack proceedings welcomes submissions along the following tracks: - Standalone Brainhack Events - OHBM Hackathons - BrainWeb Hackathons - - Neurohackademy + - Neurohackademy - Worldwide Brainhack Schools (e.g. [MTL Brainhack School](https://school.brainhackmtl.org/register/)) - -## Format -We recommend proceedings to remain under two pages. ## How are submissions reviewed? Please read our [review guidelines](REVIEWERS.md) for more information. -## How to submit? - - - Create a public account on [GitHub](https://github.com/). - - Go to [Brainhack Proceedings Template repository](https://github.com/brainhack-proceedings/template). - - Follow the instructions given in the repository [README](https://github.com/brainhack-proceedings/template/blob/master/README.md) - to create a copy of the template repository at your own local, and edit as necessary. - - [Create an issue](https://github.com/brainhack-proceedings/submit/issues/new) in this repository, using the "Submission" template, and fill in all the information. - - Our team will fork your repository on `https://github.com/brainhack-proceedings/your_paper_id`. - - We will configure a new github page, and make the paper information and pdf available on `https://brainhack-proceedings.github.io/your_paper_id`. The page will be refreshed every time a new version of the paper is released (revision1, revision2, etc). - - A review issue will be opened on the fork, inviting some reviewers. - - Reviewers will create issues. You will need to submit pull requests to address these issues. - - The editor will close each review issue after reviewing they advised was properly addressed. - - After all issues have been addressed, a "publish" release will be made by the editor. - - All versions of the paper will be posted on [https://brainhack-proceedings.github.io](https://brainhack-proceedings.github.io) right after the initial submission. - - Make sure that you archieve your repository in [Zenodo](https://guides.github.com/activities/citable-code/)or [Figshare](https://mozillascience.github.io/code-research-object/) together with your submission to Brainhack Proceedings. Doing so, you will get a Digital Object Identifier (DOI) for your repository while providing a time-free representation to your paper and associated code repositories. - ## Examples of Brainhack proceedings -The examples from the previous years' Brainhack Proceedings can be found in Proceedings menu of the [Brainhack webpage](http://www.brainhack.org/) +You can have a look at previous brainhack proceedings: + * [Brainhack proceeding 2015](https://gigascience.biomedcentral.com/articles/10.1186/s13742-016-0147-0) published in Gigascience. + * [Brainhack proceedings 2016](https://riojournal.com/topical_collection/71) Research Ideas and Outcomes. ## Attribution Some material in this section was adapted from the [Neurolibre publication guidelines](https://docs.neurolibre.com/en/latest/), released under an MIT license. diff --git a/source/Contributing to the Brainhack Proceeding.md b/source/CONTRIBUTING.md similarity index 97% rename from source/Contributing to the Brainhack Proceeding.md rename to source/CONTRIBUTING.md index 0ac6fb1..c47569e 100644 --- a/source/Contributing to the Brainhack Proceeding.md +++ b/source/CONTRIBUTING.md @@ -1,11 +1,11 @@ -# Contributing to the Brainhack Proceedings +# Contributing + +Welcome to the Brainhack Proceedings repository! In this project, contributions from the community are highly welcome. This guideline will give you all the necessary instructions to contribute to the Brainhack proceedings, whether you are new to the whole workflow or not. -Welcome to the Brainhack Proceedings repository! In this project, contributions from the community are highly welcome. This guideline will give you all the necessary instructions to contribute to the Brainhack proceedings, whether you are new to the whole workflow or not. - Please do not forget, you are welcome to contribute to the development of the Brainhack Proceedings no matter your skill level or experiences. There is no single way of contributing to open science projects. Everyone from every level of skill and experience can make a huge impact on the development of the Brainhack Proceedings. And there is no “being ready-enough” to start contributing to an open science project. You might start contributing inside of your comfort zone, and with time, switch over the other parts. Contributing to an open science project is one of the most efficient ways of learning and improving your skill sets because it is a safe environment in which to make mistakes and engage with a collaborative community. As in many open science projects, you can contribute in many ways. You can write community documents and guidelines, test the code, collect case studies, provide feedback, address issues, or start coding small bits and pieces. All of these contributions are equally important. Therefore, please do not hesitate to offer your contributions! Open science tools can only grow with community support, so any single intention of help is extremely appreciated. - + ## Table of contents Been here before? Already know what you're looking for? Jump to the following sections: - _[Joining the Brainhack community](#joining_brainhack_community)_ @@ -17,10 +17,10 @@ Been here before? Already know what you're looking for? Jump to the following se - _Example pull request_ - _[Recognizing contributions](#recognizing_contributions)_ - + ## [Joining the Brainhack Community](#joining_brainhack_community) [Brainhack Proceedings](https://github.com/brainhack-proceedings) is built around the already existing and growing Brainhack community that welcomes participation and contribution from any members of the scientific community. The best way to start contributing to an open science community and project is to actively engage with the community resources and platforms and contributing to the ongoing projects as much as you can contribute. To start your contributions to Brainhack Proceedings, you might begin with reviewing and working on the currently listed issues in the BHGs repository and get involved in discussions run on the [Brainhack Proceedings communication channels](https://mattermost.brainhack.org/brainhack/channels/brainahack-proceedings). Before you start, please make sure that you read our [Code of Conduct](https://brainhack-proceedings.readthedocs.io/en/latest/COC.html) which aims to assure creating equal, safe, and fair opportunities for every single contributor. - + ## [Code of Conduct](#code_of_conduct) If you decide to contribute to the app’s development, we ask that you and all of our contributors read and adhere to our [Code of Conduct](https://brainhack-proceedings.readthedocs.io/en/latest/COC.html) @@ -33,7 +33,7 @@ There are lots of ways to get in touch with the team maintaining Brainhack Proce This is our preferred way to answer questions so that others who have similar questions can benefit too! Even if your question is not well-defined, just post what you have so far and we will be able to point you in the right direction. -- The Github Issues +- The Github Issues - [Template Related Issues](https://github.com/brainhack-proceedings/template/issues) - [Website Related Issues](https://github.com/brainhack-proceedings/brainhack-proceedings.github.io/issues) @@ -43,34 +43,34 @@ This is our preferred way to answer questions so that others who have similar qu ## [Contributing through GitHub](#contributing_through_github) -Before you start, you'll need to set up a free [GitHub](https://github.com/) account and sign in. Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account). +Before you start, you'll need to set up a free [GitHub](https://github.com/) account and sign in. Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account). [Git](https://git-scm.com/) is a version control tool, widely used by the open-source science community, which allows contributors to track changes and sync work with the master (main) repository. [GitHub](https://github.com/) sits on top of git and supports collaborative and distributed working. If you're not yet familiar with git, there are lots of great resources to help you git started! Some of our favourites include the [git Handbook](https://guides.github.com/introduction/git-handbook/) and the [Software Carpentry](http://swcarpentry.github.io/git-novice/) [introduction to git](http://swcarpentry.github.io/git-novice/). Also, our community is here to help you as necessary. Please do not hesitate to reach out with questions and requests for the support! We are here to help! ❤️ - + ## Writing in markdown GitHub has a helpful page on [getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). -Most of the writing that you'll do will be in [Markdown](https://daringfireball.net/projects/markdown). You can think of Markdown as a few little symbols around your text that will allow GitHub to recognize and format the text. For example, you could write words as bold (`**bold**`)`, or in italics (`*italics*`), or as a link (`[link](https://https://youtu.be/dQw4w9WgXcQ)`) to another webpage. +Most of the writing that you'll do will be in [Markdown](https://daringfireball.net/projects/markdown). You can think of Markdown as a few little symbols around your text that will allow GitHub to recognize and format the text. For example, you could write words as bold (`**bold**`)`, or in italics (`*italics*`), or as a link (`[link](https://https://youtu.be/dQw4w9WgXcQ)`) to another webpage. ## [Where to start: wiki, code, and templates](#where_to_start) ### Wiki (link) -The easiest place to find information about. Review the wiki to better understand Brainhack Proceedings, use cases, and areas of improvement. +The easiest place to find information about. Review the wiki to better understand Brainhack Proceedings, use cases, and areas of improvement. ### Code (link) Although the repository is under development, we hope that users and contributors can find and share small pieces of code that are useful for getting started with the app. To contribute to the codebase you'll need to submit a pull request. Check out our pull request guidelines below. - + ### Issues -Every project on GitHub uses a set of issues to publicly list and discuss standing problems and/or missing features in the current project and allows continuing discussions over public channels. Anyone with a Github account can contribute to these discussions and take a role in decisions. Issues cover many different aspects of the project. For instance, an issue might discuss the maintenance of a piece of code or a document, it might introduce a new feature or update to bring to the project, or it might ask for help in addressing a problem with the project. Each of these issues has a set of goals and a timeline to move the project forward. By using issues, contributors can easily keep track of and address standing problems and see the assigned contributors and the urgency of the issue at hand. - -Issues should be simple, short, and require one single task. Although it can be tempting to create a giant issue that requires many steps, splitting issues into smaller pieces increases readability and allows contributors from all possible backgrounds to participate. Smaller issues also promote fair division labour among contributors as well as make auditing and tracing the issue’s progress easier. +Every project on GitHub uses a set of issues to publicly list and discuss standing problems and/or missing features in the current project and allows continuing discussions over public channels. Anyone with a Github account can contribute to these discussions and take a role in decisions. Issues cover many different aspects of the project. For instance, an issue might discuss the maintenance of a piece of code or a document, it might introduce a new feature or update to bring to the project, or it might ask for help in addressing a problem with the project. Each of these issues has a set of goals and a timeline to move the project forward. By using issues, contributors can easily keep track of and address standing problems and see the assigned contributors and the urgency of the issue at hand. + +Issues should be simple, short, and require one single task. Although it can be tempting to create a giant issue that requires many steps, splitting issues into smaller pieces increases readability and allows contributors from all possible backgrounds to participate. Smaller issues also promote fair division labour among contributors as well as make auditing and tracing the issue’s progress easier. We use labels on our issues, which indicate how each issue relates to the overall project's goals and immediate next steps. - + ### Issue Labels The current list of issue labels are here and include: @@ -80,43 +80,43 @@ The current list of issue labels are here and include: **good first issue** These issues contain tasks that are accessible to new contributors because they do not require advanced skills or a steep learning curve. -If you're not sure about how to go about contributing, these are good places to start. You'll be mentored through the contribution process by the maintenance team. If you're a seasoned contributor, please select a different issue to work on and keep these available for the newer and potentially more anxious team members. If you feel that you can contribute to one of these issues, we especially encourage you to do so! - +If you're not sure about how to go about contributing, these are good places to start. You'll be mentored through the contribution process by the maintenance team. If you're a seasoned contributor, please select a different issue to work on and keep these available for the newer and potentially more anxious team members. If you feel that you can contribute to one of these issues, we especially encourage you to do so! + **bug** These issues point to problems in the project. If you find a new bug, please give as much detail as possible in your issue, including steps to recreate the error. If you experience the same bug as one already listed, please add any additional information that you have as a comment. - + **feature** These issues introduce new features and improvements for consideration. Please try to make sure that your requested feature is distinct from any others that have already been requested or implemented. If you find one that's similar but there are subtle differences, please reference the other request in your issue. - + **enhancement** These issues suggest new updates and amendments regarding an existing feature of the project. -If you think there is a need for an enhancement in an existing feature due to the difficulties it creates in the current form, please give as much detail as possible about those difficulties. In addition, provide suggestions about potential methods/approaches to resolving those difficulties and the possible workload associated with the enhancement. - -**question** It indicates that an issue or pull request needs more information. -These issues ask questions about the project or point out areas that might need clarification and/or discussion. This label is usually used to resolve quick questions through contributor discussion in contrast to bigger issues that require resolving a bug or adding new features. Using this label will attract the contributors’ attention easily and will let them contribute to the discussions quickly. Similarly, if you see such a label on an issue, please do not hesitate to share your thoughts and suggestions. - +If you think there is a need for an enhancement in an existing feature due to the difficulties it creates in the current form, please give as much detail as possible about those difficulties. In addition, provide suggestions about potential methods/approaches to resolving those difficulties and the possible workload associated with the enhancement. + +**question** It indicates that an issue or pull request needs more information. +These issues ask questions about the project or point out areas that might need clarification and/or discussion. This label is usually used to resolve quick questions through contributor discussion in contrast to bigger issues that require resolving a bug or adding new features. Using this label will attract the contributors’ attention easily and will let them contribute to the discussions quickly. Similarly, if you see such a label on an issue, please do not hesitate to share your thoughts and suggestions. + **help wanted** It indicates a new feature, request, or enhancement. This label can include any change or upgrade that increases the project capabilities, performance, or scalability. In general, enhancements include: Additional functionality Error/bug repair and handling Better code coverage Improved performance - + **invalid** It indicates that an issue or pull request is no longer relevant. - + **dependencies** It helps to track and resolve vulnerabilities for certain types of dependencies. - + **wontfix** It indicates issues that are currently not viable to solve or out of the scope of the project - + **documentation** These issues relate to improving or updating the documentation. These are usually really great issues to help out with: the main goal of good documentation is to facilitate the contribution and use of the app without leaving any gray areas to the reader. Therefore any documents that would achieve this goal would be more than welcome! -**community** These issues relate to building and supporting the app’s community. +**community** These issues relate to building and supporting the app’s community. + +Open science projects would not live without the support of the community. Any opportunity that would allow a contribution from the community should be listed as an issue and labeled with this particular label. -Open science projects would not live without the support of the community. Any opportunity that would allow a contribution from the community should be listed as an issue and labeled with this particular label. - ## [Make a change with a pull request](#make_changes_pull_request) We appreciate all contributions and pull requests to the Brainhack Proceedings from the community. **THANK YOU** for helping us build this useful resource. We recommend that you use this workflow when contributing to the Brainhack Proceedings: - + **1. First, comment on an existing issue or open a new issue.** This allows other members of the Brainhack Proceedings development team to confirm that you aren't overlapping with work that's already underway and that all contributors are operating with shared goals. [This blog](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests) provides a nice explanation of why putting this work in upfront is so useful to everyone involved. @@ -129,35 +129,35 @@ This allows other members of the Brainhack Proceedings development team to confi Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on GitHub. For more details on how to fork a repository see this guide. This is now your own unique copy of the Brainhack Proceedings. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code! Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork) with the master repository, otherwise, you can end up with lots of dreaded [merge conflicts](https://help.github.com/articles/about-merge-conflicts. - + **3. [Clone](https://help.github.com/articles/cloning-a-repository) your forked Brainhack Proceedings repository to your machine/computer.** While you can edit files [directly on Github](https://help.github.com/articles/editing-files-in-your-repository), sometimes the changes you want to make will be complex and you will want to use a [text editor](https://en.wikipedia.org/wiki/Text_editor) that you have installed on your local machine/computer. (One great text editor is [vscode](https://code.visualstudio.com/)). -In order to work on the code locally, you must clone your forked repository. +In order to work on the code locally, you must clone your forked repository. To keep up with the changes in the Brainhack Repository, add the [Brainhack Proceeding](https://help.github.com/articles/configuring-a-remote-for-a-fork) as a remote to your locally cloned repository. Website Repository `git remote add upstream https://github.com/brainhack-proceedings/brainhack-proceedings.github.io/?` - + Template Repository `git remote add upstream https://github.com/brainhack-proceedings/template/?` - + Documentation Repository `git remote add upstream https://github.com/brainhack-proceedings/docs/?` - - + + Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) with the upstream repository. For example, to update your master branch on your local cloned repository: `git fetch upstream` `git checkout master` `git merge upstream/master` - + **4. Install the development dependencies:** - + **5. Synchronize your master branch with the upstream master branch:** `$ git checkout master` `$ git pull upstream master` - -**6. Create a [new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) to develop and maintain your proposed code changes.** + +**6. Create a [new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/) to develop and maintain your proposed code changes.** For example: `git fetch upstream` # Always start with an updated upstream `git checkout -b fix/bug-1222 upstream/master` @@ -167,11 +167,11 @@ and start making changes. Always use a feature branch. It’s good practice to n Please consider using appropriate branch names as those listed below, and mind that some of them are special (e.g., doc/ and docs/): - fix/: for bug fixes - enh/: for new features -- doc/: for documentation improvements. +- doc/: for documentation improvements. You should name all your documentation branches with the prefix doc/ or docs/ as that will preempt triggering the full battery of continuous integration tests. - - + + **7. Make the changes you've discussed** Develop the feature on your feature branch on your computer, using Git to do the version control. When you’re done editing, add changed files using git add and then git commit: `$ git add modified_files` @@ -180,11 +180,11 @@ Develop the feature on your feature branch on your computer, using Git to do the to record your changes in Git, then push the changes to your GitHub account with: `$ git push -u origin my_feature` -Try to keep the changes focused. It is generally easier to review changes that address one feature or bug at a time. It can also be helpful to test your changes locally, using a +Try to keep the changes focused. It is generally easier to review changes that address one feature or bug at a time. It can also be helpful to test your changes locally, using a Once you are satisfied with your local changes, [add/commit/push them](https://help.github.com/articles/adding-a-file-to-a-repository-using-the-command-line) to the branch on your forked repository. If you submit a large amount of work all in one go it will be much more work for whoever is reviewing your pull request. [Help them help you](https://media.giphy.com/media/uRb2p09vY8lEs/giphy.gif) 😉 If you feel tempted to "branch out" then please make a [new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository) and a [new issue](https://github.com/INCF/bids-starter-kit/issues) to go with it. - + **8. Submit [a pull request](https://help.github.com/articles/creating-a-pull-request)** Follow [these](https://help.github.com/articles/creating-a-pull-request-from-a-fork) instructions to create a pull request from your fork. This will send an email to the committers. A member of the development team will review your changes to confirm that they can be merged into the main codebase. @@ -200,7 +200,7 @@ In order to ease the reviewing process, we recommend that your contribution comp 1. **Give your pull request a helpful title** that summarises what your contribution does. This title will often become the commit message once merged so it should summarise your contribution for posterity. In some cases “Fix ” is enough. “Fix #” is never a good title. -2. **Make sure your code is properly commented and documented**, and **make sure the documentation renders properly**. +2. **Make sure your code is properly commented and documented**, and **make sure the documentation renders properly**. 3.**Tests are necessary for enhancements to be accepted**. Bug-fixes or new features should be provided with [non-regression tests](https://en.wikipedia.org/wiki/Non-regression_testing). These tests verify the correct behavior of the fix or feature. In this manner, further modifications on the codebase are granted to be consistent with the desired behavior. In the case of bug fixes, at the time of the PR, the non-regression tests should fail for the codebase in the master branch and pass for the PR code. @@ -217,18 +217,18 @@ or `make flake8-diff` which should work on unix-like systems. 8. The user guide should also include expected time and space complexity of the algorithm and scalability, e.g. “this algorithm can scale to a large number of samples > 100000, but does not scale in dimensionality: n_features is expected to be lower than 100”. -9. Moderate use of type annotations is encouraged but is not mandatory. See [mypy quickstart](https://mypy.readthedocs.io/en/latest/getting_started.html) for an introduction, as well as [pandas contributing documentation]( https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#type-hints) for style guidelines. - +9. Moderate use of type annotations is encouraged but is not mandatory. See [mypy quickstart](https://mypy.readthedocs.io/en/latest/getting_started.html) for an introduction, as well as [pandas contributing documentation]( https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#type-hints) for style guidelines. + ### Example pull request IMAGE HERE - + A maintainer/developer will review and might suggest some changes before merging them into the repository. Success!! 🎉 Well done! 🙇‍♂️ - -### Retrieving the latest code + +### Retrieving the latest code We use [Git](http://git-scm.com/) for version control and [GitHub](https://github.com/) for hosting our main repository. If you are new on GitHub and don't know how to work with it, please first have a look at [this](https://try.github.io/) to get the basics. You can check out the latest sources with the command: @@ -238,11 +238,11 @@ or if you have write privileges: `git clone git@//github.com/?` ### Installing the latest code -In order to ensure that any code changes are reflected in your installation, navigate to +In order to ensure that any code changes are reflected in your installation, navigate to your cloned Nilearn base directory and install using the following command: `pip install -e .` - - + + ## [Recognizing contributions](#recognizing_contributions) Brainhack follows the [all-contributors](https://github.com/kentcdodds/all-contributors#emoji-key) specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors here. diff --git a/source/index.rst b/source/index.rst index 8ccc8bf..c04352d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,11 +1,12 @@ Brainhack Proceedings ===================== -.. warning:: Brainhack Proceedings are at an alpha stage of development, and do not yet welcome submissions. +.. note:: Brainhack Proceedings are now open for submissions! These are the early days of this new platform, please be patient with us and consider posting an `issue `_ if you have ideas to improve these docs! -Please follow the updates from the `Brainhack `_ website, `@brainhackorg `_ Twitter account, `Brainhack Proceedings Mattermost channel `_. +Brainhack Proceedings is a community-driven, open access and free publication platform of short reports for Hackathon, Outcomes, Project, and Education (HOPE) objects! This documentation contains information for authors and reviewers about the `Brainhack Proceedings `_ workflow. + +To discuss and contribute to the development of Brainhack proceedings, please join the `Brainhack Proceedings Mattermost channel `_. You can also follow the updates of the brainhack community at `Brainhack.org `_, or on the `@brainhackorg `_ Twitter account, -Brainhack proceedings are ... .. toctree:: :maxdepth: 1 @@ -14,4 +15,5 @@ Brainhack proceedings are ... AUTHORS ARTICLE REVIEWERS + CONTRIBUTING COC