From 4bb2b6a492ab29e0e89c150d8e09cf0dc2880e6d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" <wking@tremily.us> Date: Mon, 25 Apr 2016 11:40:52 -0700 Subject: [PATCH] CONTRIBUTING: Split development notes into their own file The previous README contained notes for example-lesson developers (e.g. Git workflow notes) as well as notes for lesson consumers (e.g. _config_template.yml copying). This commit splits the former into GitHub's preferred file [1]. That ensures the license information, code of conduct, and other development-critical notes are highlighted and easily accessible to anyone filing and issue or pull-request against this repository. [1]: https://github.com/blog/1184-contributing-guidelines --- CONTRIBUTING.md | 41 +++++++++++++++++++++++++++++ README.md | 70 +++++++++++-------------------------------------- 2 files changed, 57 insertions(+), 54 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..97379c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,41 @@ +# Contributing + +[Software Carpentry][swc-site] is an open source project, +and we welcome contributions of all kinds: +new lessons, +fixes to existing material, +bug reports, +and reviews of proposed changes are all equally welcome. +By contributing, +you are agreeing that we may redistribute your work under [our license](LICENSE.md). +You also agree to abide by our [code of conduct](CONDUCT.md). + +## Getting Started + +1. We use [GitHub flow][github-flow] to manage changes. In brief: + 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. + +2. 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 major work. + +## Other Ideas + +If you are looking for other things to work on, +please see [the list of issues for this repository][issues], +or the other [Data Carpentry][dc-lessons] +and [Software Carpentry][swc-lessons] lessons. +Comments on issues and reviews of pull requests are equally welcome. + +[github-flow]: https://guides.github.com/introduction/flow/ +[repo]: https://github.com/gvwilson/new-lesson-example/ +[swc-lessons]: http://software-carpentry.org/lessons/ +[swc-site]: http://software-carpentry.org/ diff --git a/README.md b/README.md index 2e5cc10..5238099 100644 --- a/README.md +++ b/README.md @@ -3,67 +3,29 @@ lesson-example Documentation on the lesson template formatted according to the template's own rules. -## Contributing +## Layout -[Software Carpentry][swc-site] is an open source project, -and we welcome contributions of all kinds: -new lessons, -fixes to existing material, -bug reports, -and reviews of proposed changes are all equally welcome. -By contributing, -you are agreeing that we may redistribute your work under [our license][license]. -You also agree to abide by our [code of conduct][conduct]. +The layout of this repository is explained in [these episodes][rendered]. -## Getting Started - -1. We use [GitHub flow][github-flow] to manage changes. In brief: - 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. - -2. 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 major work. +1. The source for pages that appear as direct items in the navigation bar + are stored in the root directory. +2. Source files for lesson episodes are stored in `_episodes` + so that we can make use of [Jekyll collections][collections]; + `_episodes/01-xyz.md` generates `/01-xyz/index.html`, + which can be linked to using `/01-xyz/`. +3. Files that appear under the "extras" menu pulldown are stored in `_extras`. +4. Figures and other files are stored in the `files` directory, + while data sets are stored in `data` + and source code for examples in `code`. -3. Copy `_config_template.yml` to create `_config.yml` - and then edit the settings in the top half. - -4. The layout of this repository is explained in [these episodes][rendered]. - 1. The source for pages that appear as direct items in the navigation bar - are stored in the root directory. - 2. Source files for lesson episodes are stored in `_episodes` - so that we can make use of [Jekyll collections][collections]; - `_episodes/01-xyz.md` generates `/01-xyz/index.html`, - which can be linked to using `/01-xyz/`. - 3. Files that appear under the "extras" menu pulldown are stored in `_extras`. - 4. Figures and other files are stored in the `files` directory, - while data sets are stored in `data` - and source code for examples in `code`. - -## Other Resources +## Getting Started -1. For a list of helpful commands run `make` in this directory. +Copy `_config_template.yml` to create `_config.yml` and then edit the +settings in the top half. -2. If you are looking for other things to work on, - please see [the list of issues for this repository][issues], - or the other [Data Carpentry][dc-lessons] - and [Software Carpentry][swc-lessons] lessons. - Comments on issues and reviews of pull requests are equally welcome. +For a list of helpful commands run `make` in this directory. [collections]: https://jekyllrb.com/docs/collections/ -[conduct]: https://gvwilson.github.com/new-lesson-example/conduct/ [dc-lessons]: http://datacarpentry.org/lessons/ -[github-flow]: https://guides.github.com/introduction/flow/ [issues]: https://github.com/gvwilson/new-lesson-example/issues/ -[license]: https:gvwilson.github.com/new-lesson-example/license/ [rendered]: https://gvwilson.github.io/new-lesson-example/ -[repo]: https://github.com/gvwilson/new-lesson-example/ -[swc-lessons]: http://software-carpentry.org/lessons/ -[swc-site]: http://software-carpentry.org/ -- GitLab