diff --git a/_static/images/github_create_branch_from_issue.png b/_static/images/github_create_branch_from_issue.png new file mode 100644 index 0000000..08b44f4 Binary files /dev/null and b/_static/images/github_create_branch_from_issue.png differ diff --git a/_static/workflow.drawio b/_static/workflow.drawio new file mode 100644 index 0000000..1e14410 --- /dev/null +++ b/_static/workflow.drawio @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/_static/workflow.html b/_static/workflow.html new file mode 100644 index 0000000..0357f71 --- /dev/null +++ b/_static/workflow.html @@ -0,0 +1,11 @@ + + + + +Untitled Diagram + + +
+ + + \ No newline at end of file diff --git a/guidelines/workflow.rst b/guidelines/workflow.rst new file mode 100644 index 0000000..729e1be --- /dev/null +++ b/guidelines/workflow.rst @@ -0,0 +1,163 @@ + +========== + Workflow +========== + +----------- + Flowchart +----------- + +The general workflow is shown in the following flowchart. It is meant as a general guideline. +If you want to differ in your project, please document the differences at the respective locations in your project documentation. + +.. raw:: html + :file: ../_static/workflow.html + + +---------------- + Create project +---------------- + +All projects use `git `_ for version control. +`GitHub ` is used to host and manage ongoing projects. + +To create projects different *copier* templates are provided. +For the installation of *copier*, refer to the `official documentation <./https://copier.readthedocs.io/en/latest/>`. + +.. warning:: `pip install copier` will install *copier==5.1.0* as of now. Use `pip install copier==v6.0.0b0` instead. + +Existing templates are: + +* `C++ library <../copier-cpp-template>`_ +* `Documentation <../copier-documentation>`_ + +Whether you want to create a new project using a template or want to issue a new template, refer to the coding guidelines for your respective language. + +For further information on the usage of *copier*, please refer to the template documentation. + +.. note:: Sometimes it does not make sense to use one of our *copier* templates. Document your decision in the respective guidelines for the language and the documentation of the project itself. + +Every project has to use the *copier-documentation* template for consistent understanding throughout all projects. +The *copier-documentation* template is provided with all other *copier* templates. +If you do not use one of the provided *copier* templates you have to install it in the root of your project. + + +-------------------- + Problem definition +-------------------- + +The *copier-documentation* templates also provides the project with issue templates. +At the moment there are two issue templates: +- Bug Report +- Feature Request + +The templates provide the necessary guidelines to state the issue. +You can also create issues as a collection of other issues. + +An issue states a clearly defined problem which can be solved with a series of commits. +It should also contain some idea how to solve the issue or at least open a discussion. + +.. note:: For questions or general discussions, please refer to the `Discussions` tab of your project, instead of abusing the issue functionality for that, e.g. `here `_ + +----------------- + Version control +----------------- + +********** + Branches +********** + +`git `_ has to be used for all projects. +The `master` (or `main`) branch has to pass all tests at all times. + +To make changes first create an issue in the respective github repository. +Create a branch using the respective: +`Create a branch for this issue or link a pull request.` button. + +Prepend `dev/` for your branch name. +So for example a valid branch name is `dev/1_first_issue`. + +.. figure:: /_static/images/github_create_branch_from_issue.png + :align: right + :figwidth: 40% + + You can create a branch directly from the issue page. Do not forget to prepend the suggested branch name with `/dev`. + +********* + Commits +********* + +It is advised (and necessary) to use `git`s `commit` functionality. +A commit should consist of exactly one added or fixed functionality. + +.. warning:: Every commit should to come with test coverage. +Refer to the guidelines for tests for your respective language. + +For *work in progress* commits first check out appending `-wip/` to your branch name and do not forget to delete that *wip* branch as soon as it is no longer up to date. + +Always follow `the seven rules of a great Git commit message `_: + +* Separate subject from body with a blank line +* Limit the subject line to 50 characters +* Capitalize the subject line +* Do not end the subject line with a period +* Use the imperative mood in the subject line +* Wrap the body at 72 characters +* Use the body to explain what and why vs. how + + +--------- + Testing +--------- + +It is recommended to define tests on the expected behavior. +Therefore if you implement the feature, or fixed a bug the test should be passed in the end. +Testing as a process differs from project to project. +Therefore it is likely that you have to define the respective process yourself. +Please provide respective documentation, so that others and future you can adhere to the same scheme. + +.. note:: The coding guidelines for different languages define standards on how to test. If your project can not follow these, please document that and create an issue if your style should be implemented as well. + + +--------------- + Documentation +--------------- + +Documentation is mandatory and missing documentation embarassing. + +******* + Tools +******* + +The layout for documentation is provided by our *copier-documentation* template. +It is automatically included by all other templates. +The respective content is created in `docs`. + +.. warning:: If the documentation is created using the *copier* script, the `domain `_ is not set. + +Documentation is generated using `sphinx `_. +The `requirements.txt` to install the required packages is provided with the *copier* template for documentation and therefore in the `docs` folder of your project. + +Then run (in your project root) +:: + + sphinx-build ./docs /docs/build + +To create the documentation. +Your documentation is generated as `./docs/build/index.html` respectively. + +When using more than one programming language in your project, please update the `conf.py` to include the respective `domain `_. + +******** + How-To +******** + +When it comes to how to document, please keep it short and simple. +When explaining how something works, or why something is done a specific way sticks to this pattern: + + - One sentence should contain exactly one thought. + - One paragraph should contain exactly one idea. + - One chapter should contain exactly one concept. + +For flow charts or similar visual elements the usage of `diagrams.net `_ is recommended. + diff --git a/index.rst b/index.rst index fc11ef9..c0715d9 100644 --- a/index.rst +++ b/index.rst @@ -5,7 +5,9 @@ .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Guidelines: + + guidelines/workflow.rst ----------