diff --git a/doc/src/devdocs/contributing/code-changes.md b/doc/src/devdocs/contributing/code-changes.md index 14dbd65b1b5ce..41bb03f01409b 100644 --- a/doc/src/devdocs/contributing/code-changes.md +++ b/doc/src/devdocs/contributing/code-changes.md @@ -1,4 +1,6 @@ -### Contributing to core functionality or base libraries +# Code changes + +## Contributing to core functionality or base libraries *By contributing code to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).* @@ -25,7 +27,7 @@ Add new code to Julia's base libraries as follows (this is the "basic" approach; Build as usual, and do `make clean testall` to test your contribution. If your contribution includes changes to Makefiles or external dependencies, make sure you can build Julia from a clean tree using `git clean -fdx` or equivalent (be careful – this command will delete any files lying around that aren't checked into git). -#### Running specific tests +### Running specific tests There are `make` targets for running specific tests: @@ -35,7 +37,7 @@ You can also use the `runtests.jl` script, e.g. to run `test/bitarray.jl` and `t ./usr/bin/julia test/runtests.jl bitarray math -#### Modifying base more efficiently with Revise.jl +### Modifying base more efficiently with Revise.jl [Revise](https://github.com/timholy/Revise.jl) is a package that tracks changes in source files and automatically updates function @@ -74,7 +76,7 @@ system image before running the corresponding test. This can be useful as a shor on the command line (since tests aren't always designed to be run outside the runtest harness). -### Contributing to the standard library +## Contributing to the standard library The standard library (stdlib) packages are baked into the Julia system image. When running the ordinary test workflow on the stdlib packages, the system image @@ -92,11 +94,11 @@ not override the package. Be sure to change the UUID value back before making the pull request. -#### News-worthy changes +### News-worthy changes For new functionality and other substantial changes, add a brief summary to `NEWS.md`. The news item should cross reference the pull request (PR) parenthetically, in the form `([#pr])`. To add the PR reference number, first create the PR, then push an additional commit updating `NEWS.md` with the PR reference number. We periodically run `./julia doc/NEWS-update.jl` from the julia directory to update the cross-reference links, but this should not be done in a typical PR in order to avoid conflicting commits. -#### Annotations for new features, deprecations and behavior changes +### Annotations for new features, deprecations and behavior changes API additions and deprecations, and minor behavior changes are allowed in minor version releases. For documented features that are part of the public API, a compatibility note should be added into diff --git a/doc/src/devdocs/contributing/documentation.md b/doc/src/devdocs/contributing/documentation.md index 3c7b7de6bd0c1..e12ac1d482063 100644 --- a/doc/src/devdocs/contributing/documentation.md +++ b/doc/src/devdocs/contributing/documentation.md @@ -1,4 +1,4 @@ -### Improving documentation +# Improving documentation *By contributing documentation to Julia, you are agreeing to release it under the [MIT License](https://github.com/JuliaLang/julia/tree/master/LICENSE.md).* @@ -16,7 +16,7 @@ from Julia's root directory. This will rebuild the Julia system image, then inst Below are outlined the three most common types of documentation changes and the steps required to perform them. Please note that the following instructions do not cover the full range of features provided by Documenter.jl. Refer to [Documenter's documentation](https://juliadocs.github.io/Documenter.jl/stable) if you encounter anything that is not covered by the sections below. -#### Modifying files in `doc/src/` +## Modifying files in `doc/src/` Most of the source text for the Julia Manual is located in `doc/src/`. To update or add new text to any one of the existing files the following steps should be followed: @@ -33,7 +33,7 @@ To add a **new file** to `doc/src/` rather than updating a file replace step `1` 1. add the file to the appropriate subdirectory in `doc/src/` and also add the file path to the `PAGES` vector in `doc/make.jl`. -#### Modifying an existing docstring in `base/` +## Modifying an existing docstring in `base/` All docstrings are written inline above the methods or types they are associated with and can be found by clicking on the `source` link that appears below each docstring in the HTML file. The steps needed to make a change to an existing docstring are listed below: @@ -43,7 +43,7 @@ All docstrings are written inline above the methods or types they are associated 4. check the output in `doc/_build/html/` to make sure the changes are correct; 5. commit your changes and open a pull request. -#### Adding a new docstring to `base/` +## Adding a new docstring to `base/` The steps required to add a new docstring are listed below: @@ -71,7 +71,7 @@ The steps required to add a new docstring are listed below: 6. check the output in `doc/_build/html` to make sure the changes are correct; 7. commit your changes and open a pull request. -#### Doctests +## Doctests Examples written within docstrings can be used as testcases known as "doctests" by annotating code blocks with `jldoctest`. diff --git a/doc/src/devdocs/contributing/formatting.md b/doc/src/devdocs/contributing/formatting.md index e26bf865876f7..24459884223d2 100644 --- a/doc/src/devdocs/contributing/formatting.md +++ b/doc/src/devdocs/contributing/formatting.md @@ -1,6 +1,6 @@ -### Code Formatting Guidelines +# Code Formatting Guidelines -#### General Formatting Guidelines for Julia code contributions +## General Formatting Guidelines for Julia code contributions - Follow the latest dev version of [Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/). - use whitespace to make the code more readable @@ -11,7 +11,7 @@ Unicode equivalents whenever possible - in docstrings refer to the language as "Julia" and the executable as "`julia`" -#### General Formatting Guidelines For C code contributions +## General Formatting Guidelines For C code contributions - 4 spaces per indentation level, no tabs - space between `if` and `(` (`if (x) ...`) diff --git a/doc/src/devdocs/contributing/git-workflow.md b/doc/src/devdocs/contributing/git-workflow.md index 85fe9fa5e63fd..2142eed69632a 100644 --- a/doc/src/devdocs/contributing/git-workflow.md +++ b/doc/src/devdocs/contributing/git-workflow.md @@ -1,6 +1,6 @@ # Git workflow recommendations -### Git Recommendations For Pull Requests +## Git Recommendations For Pull Requests - Avoid working from the `master` branch of your fork. Create a new branch as it will make it easier to update your pull request if Julia's `master` changes. - Try to [squash](https://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) together small commits that make repeated changes to the same section of code, so your pull request is easier to review. A reasonable number of separate well-factored commits is fine, especially for larger changes. @@ -14,6 +14,6 @@ - To remove whitespace relative to the `master` branch, run `git rebase --whitespace=fix master`. -#### Git Recommendations For Pull Request Reviewers +### Git Recommendations For Pull Request Reviewers - When merging, we generally like `squash+merge`. Unless it is the rare case of a PR with carefully staged individual commits that you want in the history separately, in which case `merge` is acceptable, but usually prefer `squash+merge`. diff --git a/doc/src/devdocs/contributing/patch-releases.md b/doc/src/devdocs/contributing/patch-releases.md index dcbef6056fcce..515c2cfd35225 100644 --- a/doc/src/devdocs/contributing/patch-releases.md +++ b/doc/src/devdocs/contributing/patch-releases.md @@ -1,5 +1,4 @@ - -### Contributing to patch releases +# Contributing to patch releases The process of [creating a patch release](https://docs.julialang.org/en/v1/devdocs/build/distributing/#Point-releasing-101) is roughly as follows: diff --git a/doc/src/devdocs/contributing/tests.md b/doc/src/devdocs/contributing/tests.md index 7df203b96ffb6..c1f25da5f4a7c 100644 --- a/doc/src/devdocs/contributing/tests.md +++ b/doc/src/devdocs/contributing/tests.md @@ -1,4 +1,4 @@ -### Writing tests +# Writing tests There are never enough tests. Track [code coverage at Codecov](https://codecov.io/github/JuliaLang/julia), and help improve it.