diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index 198dd83..0000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,10 +0,0 @@ - - -> _This template is rather extensive. Fill out all that you can, if are a new contributor or you're unsure about any section, leave it unchanged and a reviewer will help you_ :smile:. _This template is simply a tool to help everyone remember the BioJulia guidelines, if you feel anything in this template is not relevant, simply delete it._ - -## What's the issue (bug, suggestion, question)? - -## Your Environment - - - diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index 0bba637..0000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,23 +0,0 @@ -# A clear and descriptive title (No issue numbers please) - -> _This template is rather extensive. Fill out all that you can, if are a new contributor or you're unsure about any section, leave it unchanged and a reviewer will help you_ :smile:. _This template is simply a tool to help everyone remember the BioJulia guidelines, if you feel anything in this template is not relevant, simply delete it._ - -## Types of changes - -This PR implements the following changes: -_(Please tick any or all of the following that are applicable)_ - -* [ ] :sparkles: New feature (A non-breaking change which adds functionality). -* [ ] :bug: Bug fix (A non-breaking change, which fixes an issue). -* [ ] :boom: Breaking change (fix or feature that would cause existing functionality to change). - -## :ballot_box_with_check: Checklist - -- [ ] :art: The changes implemented is consistent with the [julia style guide](https://docs.julialang.org/en/stable/manual/style-guide/). -- [ ] :blue_book: I have updated and added relevant docstrings, in a manner consistent with the [documentation styleguide](https://docs.julialang.org/en/stable/manual/documentation/). -- [ ] :blue_book: I have added or updated relevant user and developer manuals/documentation in `docs/src/`. -- [ ] :ok: There are unit tests that cover the code changes I have made. -- [ ] :ok: The unit tests cover my code changes AND they pass. -- [ ] :pencil: I have added an entry to the `[UNRELEASED]` section of the manually curated `CHANGELOG.md` file for this repository. -- [ ] :ok: All changes should be compatible with the latest stable version of Julia. -- [ ] :thought_balloon: I have commented liberally for any complex pieces of internal code. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index d0b21a7..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,119 +0,0 @@ -# Etiquette and conduct in BioJulia - -As you interact with other members of the BioJulia group, or make contributions -you may have revisions and suggestions on your pull request from BioJulia members -or others which they want to be implemented before they will merge your pull request. - -You may also have disagreements with people on the forums or chats maintained by -BioJulia. - -In order to keep BioJulia a civil and enjoyable place, where technical disagreements -and issues can be discussed and resolved in a mature and constructive way, we -outline three principles of etiquette we expect members and contributors to abide by. - -Anybody violating these principles in order to upset any member or contributor -may be flagged to the BioJulia admins who will decide on an appropriate -course of action. This includes locking conversations for cool-off periods, or -even bans of individuals. - -This statement on etiquette is not an exhaustive list of things that you can or can’t do. -Rather, it is a statement of our spirit and attitude towards interacting with each other. - -This statement applies in all spaces managed by the BioJulia organisation. -This includes any gitter, mailing lists, issue trackers, repositories, or any -other forums used by BioJulia for communication (such as Skype, Google Hangouts, etc). -It also applies in real-world events and spaces organised by BioJulia. - -## The principles of etiquette - -### 1. Be welcoming, friendly and patient. - -Be welcoming. We strive to welcome and support any individual participating in -BioJulia activities to any extent (from developing code, to support seeking -users). We have even been known to have a few members on our Gitter who are not -Biologists, but they enjoy the forum, like what we do, and stick around for the -programming chat. All are welcome (yes including _you_! :smile:). - -### 2. Be considerate. - -Your work will be used by other people, and you in turn will depend on the work -of others. From any code you make, to any support questions you ask or answer! -Any decision you take will affect users and colleagues, and you should take -those consequences into account when making decisions. - -Remember that we're a world-wide community, so you might not be communicating -in someone else's primary language. - -### 3. Be respectful. - -Not all of us will agree all the time, but disagreement is no excuse for poor -behaviour and poor manners. We might all experience some frustration now and then, -but we cannot allow that frustration to turn into a personal attack. -It’s important to remember that a community where people feel uncomfortable or -threatened is not a productive or fun community. -Members of the BioJulia community should be respectful when dealing with other -members as well as with people outside the BioJulia community. - -Please do not insult or put down other participants. -Harassment and other exclusionary behaviour is not acceptable. -This includes, but is not limited to: - - Violent threats or language directed against another person. - - Prejudiced, bigoted, or intolerant, jokes and language. - - Posting sexually explicit or violent material. - - Posting (or threatening to post) other people's personally identifying - information ("doxing"). - - Personal insults, especially those using racist or sexist terms. - - Unwelcome sexual attention. - - Advocating for, or encouraging, any of the above behaviour. - - Repeated harassment of others. In general, if someone asks you to stop, - then stop. - -When we disagree, try to understand why. -Disagreements, both social and technical, happen all the time and this -community is unlikely to be any exception! -It is important that we resolve disagreements and differing views constructively. -Different people have different perspectives on issues. -Being unable to understand why someone holds a viewpoint doesn’t mean that -they’re wrong. -Don’t forget that it is human to err and blaming each other doesn’t get us -anywhere. -Instead, focus on helping to resolve issues and learning from mistakes. - -Assume the person you have a disagreement with really does want the best for -BioJulia, just as you do. -Therefore, if you are ever unsure what the meaning or tone of a comment may be, -in the first instance, assume your fellow BioJulia member is acting in good -faith, this may well be a mistake in communication -(with the scientific community as diverse as it is, such mis-steps are likely!). -If you are comfortable doing so, ask them to clarify what they mean or to rephrase -their point. If you don't feel comfortable doing this, or if it is clear the -behaviour is hostile and not acceptable, please report it (see next section). - -## Is someone behaving inappropriately? - -If you are affected by the behaviour of a member or contributor of BioJulia, -we ask that you report it by contacting the -[BioJulia Admin Team](https://github.com/orgs/BioJulia/teams/admin/members) -collectively, by emailing [admin@biojulia.net](admin@biojulia.net). -They will get back to you and begin to resolve the situation. -In some cases we may determine that a public statement will need to be made. -If that's the case, the identities of all involved will remain -confidential unless those individuals instruct us otherwise. - -Ensure to include in your email: - -- Your contact info (so we can get in touch with you if we need to follow up). - -- Names (real, nicknames, or pseudonyms) of any individuals involved. - If there were other witnesses besides you, please try to include them as well. - -- When and where the incident occurred. Please be as specific as possible. - -- Your account of what occurred. If there is a publicly available record - (e.g. a mailing list archive or a public IRC logger) please include a link. - -- Any extra context you believe existed for the incident. - -- If you believe this incident is ongoing. - -- Any other information you believe we should have.s diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8802eb6..a16169e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,180 +1,18 @@ -# Contributing to BioJulia +# Contributing to Microbiome.jl and BiobakeryUtils.jl :+1::tada: First off, thanks for taking the time to contribute! :tada::+1: -The following is a set of guidelines for contributing to BioJulia repositories, -which are hosted in the [BioJulia Organization](https://github.com/BioJulia) on -GitHub. +## Etiquette and conduct -These are mostly guidelines, not rules. -Use your best judgment, and feel free to propose changes to this document in a -pull request. - -## Table of contents - -[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) - -[What should I know about BioJulia before I get started?](#what-should-i-know-about-biojulia-before-i-get-started) - -- [BioJulia Package Maintainers](#biojulia-package-maintainers) -- [BioJulia Administrators](#biojulia-administrators) -- [Etiquette and conduct](#etiquette-and-conduct) -- [Package Conventions](#package-conventions) - -[How Can I Contribute?](#how-can-i-contribute) - -- [Reporting Bugs](#reporting-bugs) -- [Suggesting an Enhancement](#suggest-an-enhancement) -- [Making Pull Requests](#pull-requests) -- [Become a BioJulia package maintainer](#become-a-biojulia-package-maintainer) - -[Styleguides](#styleguides) - -- [Git Commit Messages](#git-commit-messages) -- [Additional julia style suggestions](#additional-julia-style-suggestions) -- [Documentation Styleguide](#documentation-styleguide) - -[Additional notes](#additional-notes) - -- [A suggested branching model](#a-suggested-branching-model) - -## I don't want to read this whole thing I just have a question!!! - -We understand you are excited to get involved already! -But please don't file an issue to ask a question. -You'll get faster results by using the resources below. - -We have a Gitter message chat room where the community -chimes in with helpful advice if you have questions. -If you just have a question, or a problem that is not covered by this guide, -then come on over to the Gitter and we'll be happy to help. - -* [Gitter, BioJulia message board](https://gitter.im/BioJulia/Bio.jl) - -## What should I know about BioJulia **BEFORE** I get started? - -### BioJulia Package Maintainers - -In order to provide the best possible experience for new and existing users of -Julia from the life-sciences, a little bit of structure and organization is -necessary. - -Each package is dedicated to introducing a specific data type or algorithm, or -dealing with a specific biological problem or pipeline. - -Whilst there are some "meta-packages" such as Bio.jl, which bundle individual -packages together for convenience of installation and use, most of the BioJulia -software ecosystem is quite decentralized. - -Therefore, it made sense that maintenance of the packages should also be -fairly decentralized, to achieve this, we created the role of a "Package -Maintainer". - -The maintainer(s) for a given package are listed in the packages README.md file. - -The maintainers of a package are responsible for the following aspects of the -package they maintain. - -1. Deciding the branching model used and how branches are protected. -2. Reviewing pull requests, and issues for that package. -3. To tag releases of a package at suitable points in the lifetime of the package. -4. To be considerate and of assistance to new contributors, new community members and new maintainers. -5. To report potential incidents of antisocial to a BioJulia admin member. - -**See [HERE](#additional-notes) for extra -guidance and suggestions on branching models and tagging releases.** - -Package maintainers hold **admin** level access for any package(s) for which they -are listed as maintainer, and so new contributors to BioJulia should -rest assured they will not be 'giving up' any package they transfer to BioJulia, -they shall remain that package's administrator. Package maintainers also have -**push** (but not **admin**) access to all other code packages in the BioJulia -ecosystem. - -This allows for a community spirit where maintainers who are dedicated primarily -to other packages may step in to help other maintainers to resolve a PR or issue. -As such, newer maintainers and researchers contributing a package to the BioJulia -ecosystem can rest assured help will always be at hand from our community. - -However, if you are a maintainer stepping in to help the maintainer(s) dedicated -to another package, please respect them by first offering to step in and help, -before changing anything. Secondly, ask them before doing -advanced and potentially destructive git operations e.g forcing pushes to -branches (especially master), or re-writing history of branches. -Please defer to the judgement of the maintainers dedicated in the README of the -package. - -### BioJulia Administrators - -BioJulia has a select group of members in an Admin team. -This team has administrative access to all repositories in the BioJulia project. - -The admin team is expected to: - -1. Respond and resolve any disputes between any two BioJulia contributors. -2. Act as mentors to all other BioJulia maintainers. -3. Assist maintainers in the upkeep of packages when requested. Especially when - more difficult re-bases and history manipulation are required. -4. Some administrators maintain the BioJulia infrastructure. - This includes being responsible for the accounts and billing of any - platforms used by BioJulia, and the maintenance of any hardware like - servers owned and used by BioJulia. - -### Etiquette and conduct - -BioJulia outlines a [statement of etiquette and conduct](CODE_OF_CONDUCT.md) -that all members and contributors are expected to uphold. Please take the time -to read and understand this statement. - -### Package conventions - -First, be familiar with the official julia documentation on: - -* [Packages](https://docs.julialang.org/en/stable/manual/packages/) -* [Package Development](https://docs.julialang.org/en/stable/manual/packages/#Package-Development-1) -* [Modules](https://docs.julialang.org/en/stable/manual/modules/) - -Package names should be a simple and self explanatory as possible, avoiding -unneeded acronyms. - -Packages introducing some key type or method/algorithm should be named -accordingly. - -For example, the BioJulia package introducing biological sequence types and -functionality to process sequence data is called "BioSequences". -GitHub repository names of BioJulia packages should end in `.jl`, even though -the package name itself does not. -i.e. "BioSequences" is the name of the package, and the name of its GitHub -repository is "BioSequences.jl". - -Considerate and simple naming greatly assists people in finding the kind of -package or functionality they are looking for. - -File names of files containing julia code in packages should end in `.jl`. - -All user facing types and functions (i.e. all types and functions -exported from the module of a package), should be documented. -Documentation regarding specific implementation details that aren't relevant -to users should be in the form of comments. Please *DO* comment liberally for -complex pieces of code! - -We use [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl), -to generate user and developer documentation and host it on the web. -The source markdown files for such manuals is kept in the `docs/src/` -folder of each BioJulia package/repository. - -The code in all BioJulia packages is unit tested. Such tests should be -organized into contexts, and into separate files based on module. - -Files for tests for a module go into an appropriately named folder, within the -`test` folder in the git repo. +Contributors and maintainers for Microbiome.jl and BiobakeryUtils.jl +are expected to abide by the [Julia Community Standards](https://julialang.org/community/standards/) ## How can I contribute? +[(Adapted from the BioJulia's contributing guidelines)](https://github.com/BioJulia/Contributing) ### Reporting Bugs -Here we show you how to submit a bug report for a BioJulia repository. -If you follow the advice here, BioJulia maintainers and the community will +If you follow the advice here, we will better understand your report :pencil:, be able to reproduce the behaviour :computer: :computer:, and identify related problems :mag_right:. @@ -197,10 +35,6 @@ Please do the following: #### How to create a (good) new bug report: Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). -After you've determined [which repository](https://github.com/BioJulia) -your bug is related to, create an issue on that repository and provide the -following information by filling in [template](.github/ISSUE_TEMPLATE.md). -This template will help you to follow the guidance below. When you are creating a bug report, please do the following: @@ -252,39 +86,29 @@ When you are creating a bug report, please do the following: [code block](https://help.github.com/articles/markdown-basics/#multiple-lines) or with a link to a [gist](https://gist.github.com/). -*Note: All of the above guidance is included in the [template](.github/ISSUE_TEMPLATE.md) for your convenience.* ### Suggest an Enhancement -This section explains how to submit an enhancement proposal for a BioJulia -package. This includes completely new features, as well as minor improvements to -existing functionality. +This section explains how to submit an enhancement proposal. +This includes completely new features, as well as minor improvements to existing functionality. Following these suggestions will help maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. #### Before Submitting An Enhancement Proposal -* **Check if there's already [a package](https://github.com/BioJulia) which provides that enhancement.** - -* **Determine which package the enhancement should be suggested in.** - -* **Perform a cursory issue search** to see if the enhancement has already been suggested. - * If it has not, open a new issue as per the guidance below. - * If it has... - * Add a comment to the existing issue instead of opening a new one. - * If it was closed, take the time to understand why this was so (it's ok to - ask! :) ), and consider whether anything has changed that makes the reason - outdated. If you can think of a convincing reason to reconsider the - enhancement, feel free to open a new issue as per the guidance below. +1. **Perform a cursory issue search** to see if the enhancement has already been suggested. +2. If it has not, open a new issue as per the guidance below. +3. If it has... + 1. Add a comment to the existing issue instead of opening a new one. + 2. If it was closed, take the time to understand why this was so (it's ok to + ask! :) ), and consider whether anything has changed that makes the reason + outdated. If you can think of a convincing reason to reconsider the + enhancement, feel free to open a new issue as per the guidance below. #### How to submit a (good) new enhancement proposal Enhancement proposals are tracked as [GitHub issues](https://guides.github.com/features/issues/). -After you've determined which package your enhancement proposals is related to, -create an issue on that repository and provide the following information by -filling in [template](.github/ISSUE_TEMPLATE.md). -This template will help you to follow the guidance below. 1. **Explain the enhancement** - *Use a clear and descriptive title* for the issue to identify the suggestion. @@ -307,7 +131,7 @@ This template will help you to follow the guidance below. 2. **Provide additional context for the enhancement** - - *Explain why this enhancement would be useful* to most BioJulia users and + - *Explain why this enhancement would be useful* to users and isn't something that can or should be implemented as a separate package. - *Do you know of other projects where this enhancement exists?* @@ -318,11 +142,9 @@ This template will help you to follow the guidance below. - Specify the *name and version of the OS* you're using. -*Note: All of the above guidance is included in the [template](.github/ISSUE_TEMPLATE.md) for your convenience.* - ### Making Pull Requests -BioJulia packages (and all julia packages) can be developed locally. +All julia packages can be developed locally. For information on how to do this, see this section of the julia [documentation](https://docs.julialang.org/en/stable/manual/packages/#Package-Development-1). @@ -334,8 +156,9 @@ yourself an account on [Github](https://github.com). The chances are you already have one if you've done coding before and wanted to make any scripts or software from a science project public. -The first step to contributing is to find the -[BioJulia repository](https://github.com/BioJulia) for the package. +The first step to contributing is to find the repository for the package you want to modify +(Microbiome.jl [is here](https://github.com/EcoJulia/Microbiome.jl), +BiobakeryUtils.jl [is here](https://github.com/EcoJulia/BiobakeryUtils.jl)). Hit the 'Fork' button on the repositories page to create a forked copy of the package for your own Github account. This is your blank slate to work on, and will ensure your work and experiments won't hinder other users of the released @@ -343,10 +166,10 @@ and stable package. From there you can clone your fork of the package and work on it on your machine using git. -Here's an example of cloning, assuming you already forked the BioJulia package "BioSequences.jl": +Here's an example of cloning, assuming you already forked `Microbiome.jl`: ```sh -git clone https://github.com//BioSequences.jl.git +git clone https://github.com//Microbiome.jl.git ``` Git will download or "clone" your fork and put it in a folder called @@ -354,8 +177,8 @@ BioSequences.jl it creates in your current directory. It is beyond the scope of this document to describe good git and github use in more specific detail, as the folks at Git and GitHub have already done that wonderfully -on their own sites. If you have additional questions, simply ping a BioJulia -member or the [BioJulia Gitter](https://gitter.im/BioJulia/Bio.jl). +on their own sites. If you have additional questions, +please feel free to start a [discussion on Microbiome.jl](https://github.com/EcoJulia/Microbiome.jl/discussions/new). #### How to make (good) code contributions and new Pull-Requests @@ -381,11 +204,6 @@ member or the [BioJulia Gitter](https://gitter.im/BioJulia/Bio.jl). - Ensure that unit tests have been added which cover your code changes. - - Ensure that you have added an entry to the `[UNRELEASED]` section of the - manually curated `CHANGELOG.md` file for the package. Use previous entries as - an example. Ensure the `CHANGELOG.md` is consistent with the - recommended [changelog style](EXAMPLE_CHANGELOG.md). - - All changes should be compatible with the latest stable version of Julia. @@ -393,8 +211,6 @@ member or the [BioJulia Gitter](https://gitter.im/BioJulia/Bio.jl). 2. **In your pull request** - - **Use the [pull request template](.github/PULL_REQUEST_TEMPLATE.md)** - - *Describe* the changes in the pull request - Provide a *clear, simple, descriptive title*. @@ -417,17 +233,17 @@ member or the [BioJulia Gitter](https://gitter.im/BioJulia/Bio.jl). should provide the results of a simple performance benchmark exercise demonstrating the improvement. Especially if the changes make code less legible. -*Note: All of the above guidance is included in the [template](.github/PULL_REQUEST_TEMPLATE.md) for your convenience.* - #### Reviews and merging You can open a pull request early on and push changes to it until it is ready, or you can do all your editing locally and make a pull request only when it is finished - it is up to you. -When your pull request is ready on Github, mention one of the maintainers of the repo -in a comment e.g. `@Ward9250` and ask them to review it. You can also use Github's -review feature. They will review the code and documentation in the pull request, +When your pull request is ready on Github, +mention one of the maintainers of the repo in a comment e.g. `@kescobo` +and ask them to review it. +You can also use Github's review feature. +They will review the code and documentation in the pull request, and will assess it. Your pull request will be accepted and merged if: @@ -435,77 +251,13 @@ Your pull request will be accepted and merged if: 1. The dedicated package maintainers approve the pull request for merging. 2. The automated build system confirms that all unit tests pass without any issues. -There may be package-specific requirements or guidelines for contributors with -some of BioJulia's packages. Most of the time there will not be, the maintainers -will let you know. - It may also be that the reviewers or package maintainers will want to you to make -changes to your pull request before they will merge it. Take the time to -understand why any such request has been made, and freely discuss it with the -reviewers. Feedback you receive should be constructive and considerate +changes to your pull request before they will merge it. +Take the time to understand why any such request has been made, +and freely discuss it with the reviewers. +Feedback you receive should be constructive and considerate (also see [here](#etiquette-and-conduct)). -### Submitting a package to BioJulia - -If you have written a package, and would like to have it listed under - -and endorsed by - the BioJulia organization, you're agreeing to the following: - -1. Allowing BioJulia to have joint ownership of the package. - This is so that the members can help you review and merge pull requests and - other contributions, and also help you to develop new features. - This policy ensures that you (as the package author and current maintainer) - will have good support in maintaining your package to the highest possible - quality. - -2. Go through a joint review/decision on a suitable package name. - This usually the original package name. However, package authors may be asked - to rename their package to something more official and discoverable (by - search engines and such) if it is contentious or non-standard. - -To submit your package, follow these steps: - -1. Introduce yourself and your package on the BioJulia Gitter channel. -2. At this point maintainers will reach out to mentor and vouch for you and your package. They will: - 1. Discuss with you a suitable name. - 2. Help you ensure the the package is up to standard, and meets the code and contribution guidelines described on this site. - 3. Add you to the BioJulia organisation if you wish to become a BioJulia maintainer. - 4. Transfer ownership of the package. - -### Become a BioJulia package maintainer - -You may ask the current admin or maintainers of a BioJulia package to invite you. - -They will generally be willing to do so if you have done one or -more of the following to [contribute](#how-can-i-contribute) to BioJulia in the past: - -1. You have [submitted a new package](#submitting-a-package-to-biojulia) to BioJulia. -2. [Reported a bug](#reporting-bugs). -3. [Suggested enhancements](#suggesting-enhancements). -4. [Made one or more pull requests](#pull-requests) implementing one or more... - - Fixed bugs. - - Improved performance. - - Added new functionality. - - Increased test coverage. - - Improved documentation. - -None of these requirements are set in stone, but we prefer you to have done one -or more of the above, as it gives good confidence that you are familiar with the -tasks and responsibilities of maintaining a package used by others, and are -willing to do so. -Any other avenue for demonstrating commitment to the community and the -GitHub organisation will also be considered. - -### BioJulia members can sometimes become administrators - -Members of the admin team have often been contributing to BioJulia for a long -time, and may even be founders present at the inception of the project. -In order to become an admin, one does not necessarily have to contribute large -amounts of code to the project. -Rather the decision to on-board a member to an admin position requires a history -of using and contributing to BioJulia, and a positive -interaction and involvement with the community. Any BioJulia member fulfilling -this, may offer to take on this [responsibility](#biojulia-administrators). - ## Styleguides ### Git Commit messages @@ -531,19 +283,6 @@ this, may offer to take on this [responsibility](#biojulia-administrators). ### Additional julia style suggestions -- Source code files should have the following style of header: - - ```julia - # Title - # ===== - # - # Short description. - # - # [Long description (optional)] - # - # This file is a part of BioJulia. License is MIT: - ``` - - Indent with 4 spaces. - For functions that are not a single expression, it is preferred to use an explicit `return`. @@ -619,117 +358,3 @@ name!(node, "somename") # set node name ```julia isvalid(foo) || throw(ArgumentError("$foo is not valid")) ``` - -## Additional Notes - -### A suggested branching model - -If you are a [dedicated maintainer](#biojulia-package-maintainers) on a BioJulia -package, you may be wondering which branching model to choose for development -and maintenance of your code. - -If you are a contributor, knowing the branching model of a package may help -you work more smoothly with the maintainer of the package. - -There are several options available, including git-flow. - -Below is a recommended branching model for your repo, but it is -only a suggestion. What is best for you as the -[dedicated maintainer(s)](#biojulia-package-maintainers), is best for _you_. - -The model below is a brief summary of the ['OneFlow model'](http://endoflineblog.com/oneflow-a-git-branching-model-and-workflow). -We describe it in summary here for convenience, but we recommend you check out -the blog article as a lot more justification and reasoning is presented on _why_ -this model is the way it is. - -#### During development - -1. There is only one main branch - you can call it anything, but usually it's - called `master`. - -2. Use temporary branches for features, releases, and bug-fixes. These temporary - branches are used as a convenience to share code with other developers and as a - backup measure. They are always removed once the changes present on them are - added to master. - -3. Features are integrated onto the master branch primarily in a way which keeps - the history linear and simple. A good compromise to the rebase vs. merge commit - debate for this step is to first do an interactive rebase of the feature branch - on master, and then do a non-fast-forward merge. - Github now does squashed commits when merging a PR and this is fine too. - -_Feature Example:_ - -```sh -git checkout -b feature/my-feature master - -... Make commits to feature/my-feature to finish the feature ... - -git rebase -i master -git checkout master -git merge --no-ff feature/my-feature -git push origin master -git branch -d feature/my-feature -``` - -#### :sparkles: Making new releases - -1. You create a new branch for a new release. It branches off from `master` at the - point that you decided `master` has all the necessary features. This is not - necessarily the tip of the `master` branch. - -2. From then on new work, aimed for the _next_ release, is pushed to `master` as - always, and any necessary changes for the _current_ release are pushed to the - release branch. Once the release is ready, you tag the top of the release branch. - -3. Once the release is ready, tag the top of the release branch with a version - number. Then do a typical merge of the release branch into `master`. - Any changes that were made during the release will now be part of `master`. - Delete the release branch. - -_Release Example:_ - -```sh -git checkout -b release/2.3.0 9efc5d - -... Make commits to release/2.3.0 to finish the release ... - -git tag 2.3.0 -git checkout master -git merge release/2.3.0 -git push --tags origin master -git branch -d release/2.3.0 -git push origin :release/2.3.0 -``` - -7. Do your pushes, and go to GitHub to make your release available. - -#### :bug: Hot-fixes and hot-fix releases - -1. When a hot-fix is needed, create a hot-fix branch, that branches from the - release tag that you want to apply the fix to. - -2. Push the needed fixes to the hot-fix branch. - -3. When the fix is ready, tag the top of the fix branch with a new release, - merge it into master, finally delete the hot-fix branch. - -_Hot-fix example:_ - -```sh -git checkout -b hotfix/2.3.1 2.3.0 - -... Add commits which fix the problem ... - -git tag 2.3.1 -git checkout master -git merge hotfix/2.3.1 -git push --tags origin master -git branch -d hotfix/2.3.1 -``` - -**IMPORTANT:** -There is one special case when finishing a hot-fix branch. -If a release branch has already been cut in preparation for the next release -before the hot-fix was finished, you need to merge the hot-fix branch not to -master, but to that release branch. diff --git a/NEWS.md b/NEWS.md index 634a9bc..fa1825d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,7 +2,7 @@ ## Unreleased -- Add `commjoin` function to merge the contents of multiple `CommunityProfile`s ([#58](https://github.com/BioJulia/Microbiome.jl/pull/58)) +- Add `commjoin` function to merge the contents of multiple `CommunityProfile`s ([#58](https://github.com/EcoJulia/Microbiome.jl/pull/58)) - Add `prevalence_filter` function to select features that are present at some minumum prevalence ## v0.7.0 Major overhaul diff --git a/README.md b/README.md index 8676c85..2820ff1 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,17 @@ ## Latest Release -[![Latest Release](https://img.shields.io/github/release/BioJulia/Microbiome.jl.svg)](https://github.com/BioJulia/Microbiome.jl/releases/latest) +[![Latest Release](https://img.shields.io/github/release/EcoJulia/Microbiome.jl.svg)](https://github.com/EcoJulia/Microbiome.jl/releases/latest) [![Docs stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://biojulia.net/Microbiome.jl/stable/) -[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/BioJulia/Microbiome.jl/blob/master/LICENSE) +[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/EcoJulia/Microbiome.jl/blob/master/LICENSE) [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) ## Development Status -![BioJulia maintainer: kescobo](https://img.shields.io/badge/BioJulia%20Maintainer-kescobo-blue.svg) +![EcoJulia maintainer: kescobo](https://img.shields.io/badge/EcoJulia%20Maintainer-kescobo-blue.svg) [![Docs dev](https://img.shields.io/badge/docs-latest-blue.svg)](https://biojulia.net/Microbiome.jl/latest/) -[![CI](https://github.com/BioJulia/Microbiome.jl/workflows/CI/badge.svg)](https://github.com/BioJulia/Microbiome.jl/actions?query=workflow%3ACI) -[![codecov](https://codecov.io/gh/BioJulia/Microbiome.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/BioJulia/Microbiome.jl) +[![CI](https://github.com/EcoJulia/Microbiome.jl/workflows/CI/badge.svg)](https://github.com/EcoJulia/Microbiome.jl/actions?query=workflow%3ACI) +[![codecov](https://codecov.io/gh/EcoJulia/Microbiome.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/EcoJulia/Microbiome.jl) ## Description @@ -39,7 +39,7 @@ julia> pkg"add Microbiome#master" ## Companion Packages - You might also be interested in some functionality provided by - [BiobakeryUtils.jl](https://github.com/BioJulia/BiobakeryUtils). + [BiobakeryUtils.jl](https://github.com/EcoJulia/BiobakeryUtils). - Microbiome.jl uses [EcoBase](https://github.com/EcoJulia/EcoBase.jl) under the hood for many of its types and methods. - Microbiome.jl has a `Tables.jl` interface, so you can convert `CommunityProfiles` diff --git a/docs/make.jl b/docs/make.jl index b39d462..32ee40c 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,15 +7,16 @@ makedocs( "Samples and features" => "samples_features.md", "Profiles and Communities" => "profiles.md", "Diversity measures" => "diversity.md", - "Contributing" => "contributing.md" ], authors = "Kevin Bonham, PhD