diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4267949f87e29340f6418497a175860c692efa62..470da673c0bbbea259f521b9e3baf202d5a710cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,133 +31,9 @@ or a factual error. 3. If you are comfortable with Git, and would like to add or change material, you can submit a pull request (PR). - Instructions for doing this are [included below](#using-github). + Instructions for doing this are [included below](#using-gitlab). -## How to Contribute a Blog Post - -1. If you wish to contribute a blog post, - please work in <https://github.com/swcarpentry/website>, - which can be viewed at <https://software-carpentry.org/blog>. - -2. Posts go in the `_posts` folder, which is divided up first by year, - e.g. `2017`, and then by month, e.g. `07`. Be sure to start creating your file in - the correct folder. - -3. Posts need to be created in [Markdown](https://guides.github.com/features/mastering-markdown/) and named - according to this convention: - - `YYYY-MM-DD-filename.md` - - e.g. - - `2017-07-10-assess_report.md` - -4. In order to render correctly, posts need to have a header block, which should be created like [this example](https://raw.githubusercontent.com/swcarpentry/website/gh-pages/_posts/2017/06/2017-06-19-mqu-ttt.md), e.g. - -``` ---- -layout: post -subheadline: "Assessment" -title: "Analysis of Software Carpentry Workshop Impact" -date: 2017-07-10 -time: "08:00:00" -authors: ["Kari L. Jordan"] -category: ["surveys", "workshops", "impact", "assessment"] ---- -``` - -Separate the header block from the post proper by a new line. - -5. `Subheadline` is an optional field, as is `time`, but the other fields should be filled in. If there is more than one author, - separate the author names like this: `["Name 1", "Name 2"]`. Separate any categories the same way. - -6. Images should be uploaded to the appropriate year in the `files/<year>/<month>` folder. Images should be linked using - Markdown, and paths to the image should be relative. - Example: - ``` -  - ``` - A web link should be used for images hosted elsewhere, e.g., images you do not own, or for which you do not have rights to upload. - Example: - ``` -  - ``` - - If you are not sure how to add images in Markdown format, look at an [existing post with a locally hosted image](https://raw.githubusercontent.com/swcarpentry/website/gh-pages/_posts/2017/06/2017-06-19-mqu-ttt.md) or [one with a web link](https://raw.githubusercontent.com/swcarpentry/website/gh-pages/_posts/2017/07/2017-07-10-assess_report.md) and copy the formatting from there. - -7. Once you have previewed your file, commit the Markdown file to your fork and start a Pull Request. We automatically run tests using [TravisCI](https://travis-ci.org/) on your Pull Requests. Please review your pull request a few minutes after you've submitted it to make sure those tests have passed. These tests look for valid YAML headers and make sure that the post will build properly. - -## Other Resources - -General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site] -happens on the [discussion mailing list][discuss-list], -which everyone is welcome to join. -You can also [reach us by email][contact]. - -[contact]: mailto:admin@software-carpentry.org -[conduct]: https://software-carpentry.org/conduct/ -[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry -[dc-lessons]: http://datacarpentry.org/lessons/ -[dc-site]: http://datacarpentry.org/ -[discuss-list]: http://lists.software-carpentry.org/listinfo/discuss -[github]: http://github.com -[github-flow]: https://guides.github.com/introduction/flow/ -[github-join]: https://github.com/join -[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github -[issues]: https://github.com/swcarpentry/website/issues/ -[repo]: https://github.com/swcarpentry/website/ -[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry -[swc-lessons]: http://software-carpentry.org/lessons/ -[swc-site]: http://software-carpentry.org/ - - - -# Contributing - -[Software Carpentry][swc-site] and [Data Carpentry][dc-site] are open source projects, -and we welcome contributions of all kinds: -new lessons, -fixes to existing material, -bug reports, -and reviews of proposed changes are all welcome. - -## Contributor Agreement - -By contributing, -you agree that we may redistribute your work under [our license](LICENSE.md). -In exchange, -we will address your issues and/or assess your change proposal as promptly as we can, -and help you become a member of our community. -Everyone involved in [Software Carpentry][swc-site] and [Data Carpentry][dc-site] -agrees to abide by our [code of conduct](CONDUCT.md). - -## How to Contribute - -The easiest way to get started is to file an issue -to tell us about a spelling mistake, -some awkward wording, -or a factual error. -This is a good way to introduce yourself -and to meet some of our community members. - -1. If you do not have a [GitHub][github] account, - you can [send us comments by email][contact]. - However, - we will be able to respond more quickly if you use one of the other methods described below. - -2. If you have a [GitHub][github] account, - or are willing to [create one][github-join], - but do not know how to use Git, - you can report problems or suggest improvements by [creating an issue][issues]. - This allows us to assign the item to someone - and to respond to it in a threaded discussion. - -3. If you are comfortable with Git, - and would like to add or change material, - you can submit a pull request (PR). - Instructions for doing this are [included below](#using-github). - -## Where to Contribute +## Where to Contribute - Needs changes 1. If you wish to change the template used for workshop websites, please work in <https://github.com/swcarpentry/workshop-template>. @@ -188,69 +64,10 @@ it's easy for people who have been using these lessons for a while to forget how impenetrable some of this material can be, so fresh eyes are always welcome. -## What *Not* to Contribute - -Our lessons already contain more material than we can cover in a typical workshop, -so we are usually *not* looking for more concepts or tools to add to them. -As a rule, -if you want to introduce a new idea, -you must (a) estimate how long it will take to teach -and (b) explain what you would take out to make room for it. -The first encourages contributors to be honest about requirements; -the second, to think hard about priorities. - -We are also not looking for exercises or other material that only run on one platform. -Our workshops typically contain a mixture of Windows, macOS, and Linux users; -in order to be usable, -our lessons must run equally well on all three. +## Using GitLab -## Using GitHub - -If you choose to contribute via GitHub, -you may want to look at -[How to Contribute to an Open Source Project on GitHub][how-contribute]. -In brief: - -1. The published copy of the lesson is in the `gh-pages` branch of the repository - (so that GitHub will regenerate it automatically). - Please create all branches from that, - and merge the [master repository][repo]'s `gh-pages` branch into your `gh-pages` branch - before starting work. - Please do *not* work directly in your `gh-pages` branch, - since that will make it difficult for you to work on other contributions. - -2. We use [GitHub flow][github-flow] to manage changes: - 1. Create a new branch in your desktop copy of this repository for each significant change. - 2. Commit the change in that branch. - 3. Push that branch to your fork of this repository on GitHub. - 4. Submit a pull request from that branch to the [master repository][repo]. - 5. If you receive feedback, - make changes on your desktop and push to your branch on GitHub: - the pull request will update automatically. - -Each lesson has two maintainers who review issues and pull requests -or encourage others to do so. -The maintainers are community volunteers, -and have final say over what gets merged into the lesson. +Include instructions on forking and submitting a PR ## Other Resources -General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site] -happens on the [discussion mailing list][discuss-list], -which everyone is welcome to join. -You can also [reach us by email][contact]. - -[contact]: mailto:admin@software-carpentry.org -[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry -[dc-lessons]: http://datacarpentry.org/lessons/ -[dc-site]: http://datacarpentry.org/ -[discuss-list]: http://lists.software-carpentry.org/listinfo/discuss -[github]: http://github.com -[github-flow]: https://guides.github.com/introduction/flow/ -[github-join]: https://github.com/join -[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github -[issues]: https://github.com/swcarpentry/workshop-template/issues/ -[repo]: https://github.com/swcarpentry/workshop-template/ -[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry -[swc-lessons]: http://software-carpentry.org/lessons/ -[swc-site]: http://software-carpentry.org/ +If you have any questions or feedback, please contact us at hcc-support@unl.edu.