From 66738a489aaf9a68b8f59418897198ed97b60d38 Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Sun, 9 Oct 2022 12:30:39 +0200 Subject: [PATCH] Add CONTRIBUTING.md, fixes #391. (#511) --- CONTRIBUTING.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 28 ++++++++++++--- docs/Manifest.toml | 2 -- 3 files changed, 109 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..70a2a81acb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# Ferrite.jl contributor guide + +Welcome to Ferrite.jl contributor documentation! In this document you find +information about: + + - [Documentation](#documentation) + - [Reporting issues](#reporting-issues) + - [Code changes](#reporting-issues) + +If you are new to open source development in general there are many guides online to help +you get started, for example [first-contributions][first-contributions]. Another great +resource, which specifically discusses Julia contributions, is the video [Open source, Julia +packages, git, and GitHub][tim-git]. + +## Documentation + +Contributing to documentation is a great way to get started with any new project. As a new +user you have a unique perspective of what things need to be documented and explained better +-- if something confuses you, chances are you're not alone. Remember that also simple +changes like fixing typos are welcome contributions. If you are looking for specific things +to work on you can look at [open issues][open-issues]. + +Small changes can be done easily in GitHub's web interface (see [Editing +files][gh-edit-files]). Every page in the documentation have an `Edit on GitHub` button at +the top, which takes you to the correct source file. The video [Making Julia documentation +better][tim-doc] guides you through these steps. + +Making larger changes is easier locally after cloning the repository. With a local +repository you can also preview the changes in your own browser. After starting a Julia REPL +in the root of the repository you can execute the following snippet: + +```julia +include("docs/liveserver.jl") +``` + +This uses [`LiveServer.jl`][liveserver] to launch a local webserver which you can visit at +[http://localhost:8000](http://localhost:8000). `LiveServer.jl` will monitor changes to the +source files. When you make a change, and save the file, `LiveServer.jl` will automatically +rebuild the documentation, and automatically refresh your browser window. Note that the +first build may take longer, but subsequent runs should be substantially faster and give you +almost instant feedback in the browser. + +**Useful resources** + - General information about documenting Julia code in the [Julia manual][julia-doc]. + - [Documentation for `Documenter.jl`][documenter] which is used to render the HTML pages. + - [Documentation for `Literate.jl`][literate] which is used for tutorials/examples. + + +## Reporting issues + +If you have found a bug or a problem with Ferrite.jl you can open an [issue][new-issue]. Try +to include as much information about the problem as possible and preferably some code that +can be copy-pasted to reproduce it (see [How to create a Minimal, Reproducible +Example][so-mre]). + +If you can identify a fix for the bug you can submit a pull request without first opening an +issue, see [Code changes](#code-changes). + + +## Code changes + +Bug fixes and improvements to the code, or to the unit tests are always welcome. If you have +ideas about new features or functionality it might be good to first open an +[issue][new-issue] or [discussion][new-discussion] to get feedback before spending too much +time implementing something. + +If you are looking for specific things to work on you can look at [open +issues][open-issues]. + +Remember to always include (when applicable): i) unit tests which exercises the new code, +ii) documentation, iii) a note in the [CHANGELOG.md](CHANGELOG.md) file. + + +[documenter]: https://juliadocs.github.io/Documenter.jl/ +[first-contributions]: https://github.com/firstcontributions/first-contributions +[gh-edit-files]: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files#editing-files-in-another-users-repository +[julia-doc]: https://docs.julialang.org/en/v1/manual/documentation/ +[literate]: https://fredrikekre.github.io/Literate.jl/v2/ +[liveserver]: https://github.com/tlienart/LiveServer.jl +[new-discussion]: https://github.com/Ferrite-FEM/Ferrite.jl/discussions/new +[new-issue]: https://github.com/Ferrite-FEM/Ferrite.jl/issues/new +[open-issues]: https://github.com/Ferrite-FEM/Ferrite.jl/issues +[so-mre]: https://stackoverflow.com/help/minimal-reproducible-example +[tim-doc]: https://youtu.be/ZpH1ry8qqfw +[tim-git]: https://youtu.be/cquJ9kPkwR8 diff --git a/README.md b/README.md index 7b2cbb1f19..a5735bfb9b 100644 --- a/README.md +++ b/README.md @@ -21,11 +21,31 @@ You can install Ferrite from the Pkg REPL: pkg> add Ferrite ``` -## Contributing and Questions -If you have specific questions about Ferrite.jl, you're welcome to reach out to us on the Julia Slack under #ferrite-fem or on Zulip under #Ferrite.jl ([here](https://julialang.org/community/) you can find links to Slack and Zulip). If you encounter a problem, please open an [issue](https://github.com/Ferrite-FEM/Ferrite.jl/issues). Feel free to ask us in case you are not sure if a problem is on the side of Ferrite.jl! -Contributions are very welcome, as are feature requests and suggestions. -Please keep in mind that we are part of the Julia community and adhere to the [Julia Community Standards](https://julialang.org/community/standards/). +## Contributing + +Contributions in all forms (bug reports, documentation, features, suggestions, ...) are very +welcome. See [CONTRIBUTING](CONTRIBUTING.md) for more details. + +## Questions + +If you have questions about Ferrite.jl you're welcome to reach out to us on the Julia Slack +under `#ferrite-fem` or on Zulip under `#Ferrite.jl` ([links to Slack and +Zulip][community]). Alternatively you can start a [new discussion][gh-discussion] in the +discussion forum on the repository. Feel free to ask us even if you are not sure the problem +is with Ferrite.jl. + +If you encounter what you think is a bug please report it, see +[CONTRIBUTING.md](CONTRIBUTING.md#reporting-issues) for more information. + +## Community Standards + +Please keep in mind that we are part of the Julia community and adhere to the +[Julia Community Standards][standards]. [docs-dev-img]: https://img.shields.io/badge/docs-latest%20release-blue [docs-dev-url]: http://ferrite-fem.github.io/Ferrite.jl/ + +[standards]: https://julialang.org/community/standards/ +[community]: https://julialang.org/community/ +[gh-discussion]: https://github.com/Ferrite-FEM/Ferrite.jl/discussions/new diff --git a/docs/Manifest.toml b/docs/Manifest.toml index 48b97997a2..3ed6ce7e80 100644 --- a/docs/Manifest.toml +++ b/docs/Manifest.toml @@ -772,8 +772,6 @@ version = "2.14.0" [[deps.LiveServer]] deps = ["HTTP", "MIMEs", "Pkg", "Sockets"] git-tree-sha1 = "af11a3662103715954be5042747bd98cb1dc4229" -repo-rev = "fe/include-dirs" -repo-url = "https://github.com/fredrikekre/LiveServer.jl" uuid = "16fef848-5104-11e9-1b77-fb7a48bbb589" version = "1.1.0"