From 7e9f08ea03d89bd4a849a63d6aef9c8d0a263777 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Wed, 18 Nov 2020 12:56:59 +0100 Subject: [PATCH 1/2] Improve CONTRIBUTING.md Signed-off-by: David Mehren Co-authored-by: Erik Michelson (cherry picked from commit f77f9fac19e6ffbcf41e00b17791ef4d042cad3b) Signed-off-by: David Mehren --- CONTRIBUTING.md | 95 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 68 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 781e0d919..b6f91ac80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,78 @@ -# Contributing +# Contributing to HedgeDoc -When contributing to this repository, please first discuss the change you wish to make via issue, -email, or any other method with the owners of this repository before making a change. +Thanks for your help in improving the HedgeDoc project! -Please note we have a [code of conduct](CODE_OF_CONDUCT.md), please follow it in all your -interactions with the project. +Please note we have a [code of conduct][code-of-conduct], please follow it in all your interactions with the project. -## Pull Request Process -1. Ensure you signed all your commits with Developer Certificate of Origin (DCO). -2. Ensure any install or build dependencies are removed before the end of the layer when doing a - build. -3. Update the README.md with details of changes to the interface, this includes new environment - variables, exposed ports, useful file locations and container parameters. -4. Increase the version numbers in any examples files and the README.md to the new version that this - Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -5. You may merge the Pull Request in once you have the sign-off of two other developers, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. +## Ways of contributing -## Sign your work +### Do you have questions about the project? + +* Feel free to post your question on our [community forum](community-forum) or join + our [matrix community chat][matrix-support]. + +### Did you find a bug? + +* **Ensure the bug wasn't already reported** by searching on GitHub under [Issues](issues). + +* If you're unable to find an open issue addressing the problem, [open a new one](new_issue). Be sure to use one of the + templates we provide if your request applies to them. + +### Did you write a patch that fixes a bug? + +* Open a new GitHub pull request with the patch. See the section [submitting a pull request](#submitting-a-pull-request) + for details on this. + +* Ensure the PR description is precise about the problem and your solution. Just fill out our template. That should + cover the most important information. + +### Do you intend to add a new feature or change an existing one? + +* Suggest your idea via a new GitHub issue. After a confirmation about your idea, you can start writing code. Our + maintainers and other project developers can provide useful details about the architecture and show you relevant + issues and discussions. + +### Do you want to work on translations? + +* If you want to improve a translation or add a new translation altogether, we handle those via [POEditor](poeditor). + +HedgeDoc is a volunteer effort. We encourage you to pitch in and to help us making this project even better. + +## Certificate of Origin + +By contributing to this project you agree to +the [Developer Certificate of Origin (DCO)](docs/legal/developer-certificate-of-origin.txt). This document was created +by the Linux Kernel community and is a simple statement that you, as a contributor, have the legal right to make the +contribution. The DCO is a legally binding statement, +please [read it carefully](docs/legal/developer-certificate-of-origin.txt). -We use the Developer Certificate of Origin (DCO) as a additional safeguard -for the CodiMD project. This is a well established and widely used -mechanism to assure contributors have confirmed their right to license -their contribution under the project's license. -Please read [docs/legal/developer-certificate-of-origin.txt][dcofile]. If you can certify it, then just add a line to every git commit message: -```` +``` Signed-off-by: Random J Developer -```` +``` Use your real name (sorry, no pseudonyms or anonymous contributions). -If you set your `user.name` and `user.email` git configs, you can sign your -commit automatically with `git commit -s`. You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases) -like `git config --global alias.ci 'commit -s'`. Now you can commit with -`git ci` and the commit will be signed. + +If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. +You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases) +like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci` and the commit will be signed. + +## Submitting a Pull Request + +1. Submit an issue describing your proposed change. We will try to respond to your issue promptly. +2. Fork this repo, develop and test your code changes. Ensure you signed all your commits (see above for details). +3. Submit a pull request against this repo's `master` branch. +4. Your branch may be merged once all configured checks pass. + +[code-of-conduct]: ./CODE-OF-CONDUCT.md + +[community-forum]: https://community.hedgedoc.org + +[matrix-support]: https://matrix.to/#/#hedgedoc:matrix.org + +[issues]: https://github.com/hedgedoc/hedgedoc/issues + +[new_issue]: https://github.com/hedgedoc/hedgedoc/issues/new/choose + +[poeditor]: https://translate.hedgedoc.org From a27524b9be824634d1130b4ec7612efead6ea0a4 Mon Sep 17 00:00:00 2001 From: David Mehren Date: Mon, 4 Jan 2021 14:54:19 +0100 Subject: [PATCH 2/2] Update readme and contribution docs for 2.0 development Signed-off-by: David Mehren --- CONTRIBUTING.md | 7 ++- README.md | 129 +++++++++++++++++------------------------------- 2 files changed, 49 insertions(+), 87 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6f91ac80..adf079878 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,9 @@ Please note we have a [code of conduct][code-of-conduct], please follow it in al * Ensure the PR description is precise about the problem and your solution. Just fill out our template. That should cover the most important information. +* Please note that we only accept PRs for the 1.x releases if they fix critical issues. If you are unsure if your fix is + critical, it's best to ask us before you start coding. + ### Do you intend to add a new feature or change an existing one? * Suggest your idea via a new GitHub issue. After a confirmation about your idea, you can start writing code. Our @@ -36,7 +39,7 @@ Please note we have a [code of conduct][code-of-conduct], please follow it in al * If you want to improve a translation or add a new translation altogether, we handle those via [POEditor](poeditor). -HedgeDoc is a volunteer effort. We encourage you to pitch in and to help us making this project even better. +HedgeDoc is a volunteer effort. We encourage you to pitch in and help us to make this project even better. ## Certificate of Origin @@ -62,7 +65,7 @@ like `git config --global alias.ci 'commit -s'`. Now you can commit with `git ci 1. Submit an issue describing your proposed change. We will try to respond to your issue promptly. 2. Fork this repo, develop and test your code changes. Ensure you signed all your commits (see above for details). -3. Submit a pull request against this repo's `master` branch. +3. Submit a pull request against this repo's `develop` branch. 4. Your branch may be merged once all configured checks pass. [code-of-conduct]: ./CODE-OF-CONDUCT.md diff --git a/README.md b/README.md index 87d2cead7..0ebceaab3 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,65 @@ -HedgeDoc +HedgeDoc 2 === -## **Warning**: The `develop` branch contains unstable code. Not suitable for production use! See [here](docs/dev/2.0.md) for development documentation. - -[![#CodiMD on matrix.org][matrix.org-image]][matrix.org-url] -[![build status][travis-image]][travis-url] +[![#HedgeDoc on matrix.org][matrix.org-image]][matrix.org-url] [![version][github-version-badge]][github-release-page] [![POEditor][poeditor-image]][poeditor-url] [![Mastodon][social-mastodon-image]][social-mastodon] -CodiMD lets you create real-time collaborative markdown notes. You can test-drive -it by visiting our [CodiMD demo server][codimd-demo]. +HedgeDoc lets you create real-time collaborative markdown notes. Have a look at [our website](https://hedgedoc.org) for +more details. -It is inspired by Hackpad, Etherpad and similar collaborative editors. This -project originated with the team at [HackMD](https://hackmd.io) and now forked -into its own organisation. [A longer writeup can be read in the history doc](docs/history.md). - -[![CodiMD 1.3.2 with its feature demonstration page open](docs/images/CodiMD-1.3.2-features.png)][codimd-demo-features] +**Important:** We are currently working on HedgeDoc 2, a complete rewrite of HedgeDoc. Please note the following: +- This branch contains the latest development code and does not implement all features yet. If you are looking for the + 1.x source code, have a look at the `master` branch. +- HedgeDoc 2 will be split in two components: the backend (this repo) and the frontend in + the [react-client repo](https://github.com/hedgedoc/react-client). +- The 1.x release is maintenance-only. We do not accept feature requests or PRs for this release anymore and may choose + to close non-critical bug reports, if the bug will be non-existent in 2.0. ## Community and Contributions -We welcome contributions! There's a lot to do: If you would like to report bugs, -the [issue tracker][github-issue-tracker] is the right place. If you can help -translating, find us on [POEditor][poeditor-url]. To get started developing, -take a look at the [docs/dev](docs/dev) directory. In any case: come talk to us, -we'll be delighted to help you with the first steps. +We welcome contributions! +Have a look at our [contribution docs](CONTRIBUTING.md) to find out how you can help. If you want to contribute to +HedgeDoc 2, please join our [development chat][matrix.org-dev-url]. To stay up to date with our work or get support it's recommended to join our -[Matrix channel][matrix.org-url], stop by our [community forums][codimd-community] +[Matrix channel][matrix.org-url], stop by our [community forums][hedgedoc-community] or subscribe to the [release feed][github-release-feed]. We also engage in -regular [community calls][codimd-community-calls] ([RSS](https://community.codimd.org/t/codimd-community-call/19.rss)) which you are very welcome to join. - - -## Installation / Upgrading - -You can run CodiMD in a number of ways, and we created setup instructions for -all of these: - -* [Docker](docs/setup/docker.md) -* [Kubernetes](docs/setup/kubernetes.md) -* [Cloudron](docs/setup/cloudron.md) -* [LinuxServer.io (multi-arch docker)](docs/setup/docker-linuxserver.md) -* [Heroku](docs/setup/heroku.md) -* [Manual setup](docs/setup/manual-setup.md) - -If you do not wish to run your own setup, you can find a commercial offering at -https://hackmd.io. This is not the same codebase as this one, but it is a very -similar project. - - -## Configuration - -Theres two main ways to configure your CodiMD instance: -[Config file](docs/configuration-config-file.md) or -[environment variables](docs/configuration-env-vars.md). You can choose what -works best for you. - -CodiMD can integrate with - -* facebook, twitter, github, gitlab, dropbox, google, ldap, saml and [oauth2](docs/guides/auth/oauth.md) **for login** -* imgur, s3, minio, azure **for image/attachment storage** (files can also be local!) -* dropbox **for export and import** - -More info about that can be found in the configuration docs above. - - -## Browser support - -To use CodiMD, your browser should match or exceed these versions: - -- ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/chrome/chrome_24x24.png) Chrome >= 47, ![Chrome](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/chrome/chrome_24x24.png) Chrome for Android >= 47 -- ![Safari](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/safari/safari_24x24.png) Safari >= 9, ![iOS Safarai](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/safari-ios/safari-ios_24x24.png) iOS Safari >= 8.4 -- ![Firefox](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/firefox/firefox_24x24.png) Firefox >= 44 -- ![IE](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/archive/internet-explorer_9-11/internet-explorer_9-11_24x24.png) IE >= 9, ![Edge](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/edge/edge_24x24.png) Edge >= 12 -- ![Opera](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/opera/opera_24x24.png) Opera >= 34, ![Opera Mini](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/opera-mini/opera-mini_24x24.png) Opera Mini not supported -- ![Android Browser](https://raw.githubusercontent.com/alrra/browser-logos/HEAD/src/android-webview-beta/android-webview-beta_24x24.png) Android Browser >= 4.4 - - -## Related Tools - -Our community has created related tools, we'd like to highlight [codimd-cli](https://github.com/codimd/cli) -which lets you use CodiMD from the comfort of your command line. - +regular [community calls][hedgedoc-community-calls] ([RSS](https://community.codimd.org/t/codimd-community-call/19.rss)) +which you are very welcome to join. # License Licensed under AGPLv3. For our list of contributors, see [AUTHORS](AUTHORS). -[matrix.org-image]: https://img.shields.io/matrix/codimd:matrix.org?logo=matrix&server_fqdn=matrix.org -[matrix.org-url]: https://riot.im/app/#/room/#codimd:matrix.org -[travis-image]: https://travis-ci.org/codimd/server.svg?branch=master -[travis-url]: https://travis-ci.org/codimd/server -[github-version-badge]: https://img.shields.io/github/release/codimd/server.svg -[github-release-page]: https://github.com/codimd/server/releases -[github-release-feed]: https://github.com/codimd/server/releases.atom -[github-issue-tracker]: https://github.com/codimd/server/issues/ +[matrix.org-image]: https://img.shields.io/matrix/hedgedoc:matrix.org?logo=matrix&server_fqdn=matrix.org + +[matrix.org-url]: https://chat.hedgedoc.org + +[matrix.org-dev-url]: https://chat.hedgedoc.org/dev + +[github-version-badge]: https://img.shields.io/github/release/hedgedoc/hedgedoc.svg + +[github-release-page]: https://github.com/hedgedoc/hedgedoc/releases + +[github-release-feed]: https://github.com/hedgedoc/hedgedoc/releases.atom + +[github-issue-tracker]: https://github.com/hedgedoc/hedgedoc/issues/ + [poeditor-image]: https://img.shields.io/badge/POEditor-translate-blue.svg + [poeditor-url]: https://poeditor.com/join/project/1OpGjF2Jir -[codimd-demo]: https://demo.codimd.org -[codimd-demo-features]: https://demo.codimd.org/features -[codimd-community]: https://community.codimd.org -[codimd-community-calls]: https://community.codimd.org/t/codimd-community-call/19 -[social-mastodon]: https://social.codimd.org/mastodon -[social-mastodon-image]: https://img.shields.io/mastodon/follow/18547?domain=https%3A%2F%2Fsocial.snopyta.org&style=social + +[hedgedoc-demo]: https://demo.hedgedoc.org + +[hedgedoc-demo-features]: https://demo.hedgedoc.org/features + +[hedgedoc-community]: https://community.hedgedoc.org + +[hedgedoc-community-calls]: https://community.hedgedoc.org/t/codimd-community-call/19 + +[social-mastodon]: https://social.hedgedoc.org/mastodon + +[social-mastodon-image]: https://img.shields.io/mastodon/follow/49593?domain=https%3A%2F%2Fsocial.snopyta.org&style=social