TrainRun.jl/CONTRIBUTING.md

113 lines
5.6 KiB
Markdown
Raw Normal View History

# Contributing
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.
Please note we have a code of conduct, please follow it in all your interactions with the project.
## Julia Development Environment
2022-04-28 17:02:40 +02:00
Link your local git repository to Julia:
```console
2022-05-04 16:53:58 +02:00
$ ln -s ~/path/to/TrainRuns.jl ~/.julia/dev/TrainRuns
2022-04-28 17:02:40 +02:00
```
Have a look how to develop Julia packages: https://github.com/ShozenD/julia-pkg-dev
You might want to use `Revise.jl` as well:
```julia
Pkg.add("Revise")
```
and then just load with `using Revise` (preferably by putting it in the `~/.julia/config/startup.jl` file).
2022-05-04 16:53:58 +02:00
You can overide the standard TrainRuns package with the local development branch (see linking above) with:
```julia
julia> # use the ] key
2022-05-04 16:53:58 +02:00
(@v1.x) pkg> develop TrainRuns
(@v1.x) pkg> # use backspace
2022-05-04 16:53:58 +02:00
julia> using TrainRuns # local development branch will be loaded
```
If you want to add a dependency use:
```julia
julia> # use the ] key
2022-05-04 16:53:58 +02:00
(@v1.x) pkg> activate TrainRuns
(TrainRuns) pkg>
```
2022-04-28 17:02:40 +02:00
2022-05-08 21:43:21 +02:00
## Files in TrainRuns
| file | concern |
| --------------- | ------------------------------ |
| TrainRuns.jl | main file and function |
| types.jl | special TrainRuns types |
| constructors.jl | type constructors |
| formulary.jl | formulars from literature |
| output.jl | transformation into DataFrames |
## Reporting Issues
* It's always good to start with a quick search for an existing issue to post on,
or related issues for context, before opening a new issue
* Including minimal examples is greatly appreciated
* If it's a bug, or unexpected behaviour, reproducing on the latest development version
2022-05-04 16:53:58 +02:00
(`Pkg.add(name="TrainRuns", rev="main")`) is a good gut check and can streamline the process,
along with including the first two lines of output from `versioninfo()`
## Style Guidelines
TODO
2022-04-28 17:02:40 +02:00
## Git Recommendations For Pull Requests
* Avoid working from the `main` branch of your fork, creating a new branch will make it
2022-05-04 16:53:58 +02:00
easier if TrainRuns.jl `main` branch changes and you need to update your pull request;
* All PRs and issues should be opened against the `main` branch not against the current release;
* Run tests of your code before sending any commit to GitHub. Only push changes when
the tests of the change are passing locally. In particular note that it is not a problem
if you send several commits in one push command to GitHub as CI will be run only once then;
2022-05-04 16:53:58 +02:00
* If any conflicts arise due to changes in TrainRuns.jl `main` branch, prefer updating your pull
request branch with `git rebase` (rather than `git merge`), since the latter will introduce a merge
commit that might confuse GitHub when displaying the diff of your PR, which makes your changes more
difficult to review. Alternatively use conflict resolution tool available at GitHub;
* Please try to use descriptive commit messages to simplify the review process;
* Using `git add -p` or `git add -i` can be useful to avoid accidently committing unrelated changes;
* Maintainers get notified of all changes made on GitHub. However, what is useful is writing a short
message after a sequence of changes is made summarizing what has changed and that the PR is ready
for a review;
* When linking to specific lines of code in discussion of an issue or pull request, hit the `y` key
while viewing code on GitHub to reload the page with a URL that includes the specific commit that
you're viewing. That way any lines of code that you refer to will still be correct in the future, even
if additional commits are pushed to the branch you are reviewing;
* Please make sure you follow the code formatting guidelines when submitting a PR;
Also preferably do not modify parts of code that you are not editing as this makes
reviewing the PR harder (it is better to open a separate maintenance PR
if e.g. code layout can be improved);
* If a PR is not finished yet and should not be reviewed yet then it should be opened as DRAFT
(in this way maintainers will know that they can ignore such PR until it is made non-draft or the author
asks for a review).
2022-06-20 14:10:38 +02:00
## Contribution Ideas
Models for:
* Breakaway (currently simple like acceleration)
* braking (currently constant braking with a certain value)
* inhomogeneous mass band (consider non-uniform mass distribution (cf. Wende, 2003 p. 96f.))
2022-12-19 13:44:41 +01:00
* double traction
2022-06-20 14:10:38 +02:00
More exact calculation of resistances for:
* the track (e.g. including curves, switches, tunnels)
* for the train (e.g. there are vehicle resistance equations especially for high-speed trains, which are not yet considered in the tool (cf. Wende, 2003 p. 152 f.))
2022-12-19 13:44:41 +01:00
* Input/calculation of tractive force (currently only tractive force-speed pairs. This could be extended to include tractive force functions that apply to specific velocity ranges (cf. BrĂ¼nger, et al., 2014 p. 69).
2022-06-20 14:10:38 +02:00
2022-12-19 13:44:41 +01:00
* Calculation of energy, cf. (Wende, 2003 p. 324).
* Energy-saving driving: https://doi.org/10.1016/j.ejor.2016.09.044
2022-06-20 14:10:38 +02:00
2022-12-19 13:44:41 +01:00
* switching between different step variables in one train run or implementation of variable step size (currently it is necessary to choose between s, t and v and to specify a step size that becomes smaller at intersections, but is otherwise constant)
2022-06-20 14:10:38 +02:00
2022-12-19 13:44:41 +01:00
* introduce a driving regime in trainrun() with a velocity > 0 at the starting point and a milage != 0 for the starting point
i.e. trainrun(train::Train, path::Path, regime=Regime()::Regime, settings=Settings()::Settings)
e.g. Regime((v1,milage1),(v2,milage2),...,(vX,milageX)) v=(Int,v_max,coasting,halt)
2022-06-20 14:10:38 +02:00
2022-12-19 13:44:41 +01:00
* good plots would be nice