You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+35-44Lines changed: 35 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,6 @@
2
2
3
3
💫⚙️🤖 We're excited that you're here and want to contribute. 🤖⚙️💫
4
4
5
-
By joining our efforts, you will be helping to democratise emulation for Digital Twins and beyond.
6
-
7
5
We want to ensure that every user and contributor feels welcome, included and supported to participate in the AutoEmulate community. Whether you're a seasoned developer, a machine learning researcher, a data scientist, or just someone eager to learn and contribute, **you are welcome here**. We value every contribution, be it big or small, and we appreciate the unique perspectives you bring to the project.
8
6
9
7
We hope that the information provided in this document will make it as easy as possible for you to get involved. If you find that you have questions that are not discussed below, please let us know through one of the many ways to [get in touch](#get-in-touch).
@@ -12,86 +10,69 @@ We hope that the information provided in this document will make it as easy as p
12
10
13
11
If you'd like to find out more about AutoEmulate, make sure to check out:
14
12
15
-
1.**README**: For a high-level overview of the project, please refer to our README.
13
+
1.**README**: For a high-level overview of the project, please refer to our [README](https://github.com/alan-turing-institute/autoemulate/blob/main/README.md).
16
14
2.**Documentation**: For more detailed information about the project, please refer to our [documentation](https://alan-turing-institute.github.io/autoemulate).
17
-
3.**Project Roadmap**: Familiarise yourself with our direction and goals by checking out [the project's project board](https://github.com/orgs/alan-turing-institute/projects/185/views/4) in lieu of a formal product roadmap.
18
-
19
-
## Get in touch
20
-
21
-
The easiest way to get involved with the active development of AutoEmulate is to join our sprints. If you are looking to become part of the core development team in this way, reach out to Research Application Manager Kalle Westerling via email [email protected] to request an invite.
22
15
23
-
<!-- The easiest way to get involved with the active development of AutoEmulate is to join our regular community calls. The community calls are currently on a hiatus but if you are interested in participating in the forthcoming community calls, which will start in 2024, you should join our Slack workspace, where conversation about when to hold the community calls in the future will take place. -->
24
-
25
-
<!--
26
-
**Slack Workspace**: Join our [AutoEmulate Slack channel](<LINK TO SIGN-UP OR TO THE SLACK TEAM>) for discussions, queries, and community interactions. Send us an email at [email protected] to request an invite.
27
-
-->
16
+
## How to Contribute
28
17
29
-
**Email**: If you prefer a formal communication method or have specific concerns, please reach us via lead Research Software Engineer Martin Stoffel, [email protected].
18
+
This section provides a high-level guide to contributing to AutoEmulate, designed for those with little or no experience with open source projects. For more detailed information, please also refer to the docs for:
We welcome contributions of all kinds, be it code, documentation, or community engagement. We encourage you to read through the following sections to learn more about how you can contribute to the package.
34
24
35
-
We are always interested in adding more simulations or simulation input/output datasets from any field (see https://github.com/alan-turing-institute/autoemulate/issues/4).
36
-
37
25
## How to Submit Changes
38
26
39
27
We follow the same instructions for submitting changes to the project as those developed by [The Turing Way](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md#making-a-change-with-a-pull-request). In short, there are five steps to adding changes to this repository:
40
28
41
29
1.**Fork the Repository**: Start by [forking the AutoEmulate repository](https://github.com/alan-turing-institute/autoemulate/fork).
42
-
1.**Make Changes**: Ensure your code adheres to the style guidelines and passes all tests.
43
-
2.**Commit and Push**: Use clear commit messages.
44
-
3.**Open a Pull Request**: Ensure you describe the changes made and any additional details.
30
+
2.**Make Changes**: Ensure your code follows the existing code style ([PEP 8](https://peps.python.org/pep-0008/)) and passes all tests.
31
+
3.**Commit and Push**: Use clear commit messages.
32
+
4.**Open a Pull Request**: Ensure you describe the changes made and any additional details.
45
33
46
34
### 1. Fork the Repository
47
35
48
36
Once you have [created a fork of the repository](https://github.com/alan-turing-institute/autoemulate/fork), you now have your own unique local copy of AutoEmulate. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code!
49
37
50
38
Make sure to [keep your fork up to date](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) with the main repository, otherwise, you can end up with lots of dreaded [merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts).
51
39
52
-
If you prefer working with GitHub in the browser, [these instructions](https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser) describe how to sync your fork to the original repository.
53
-
54
40
### 2. Make Changes
55
41
56
-
Try to keep the changes focused. If you submit a large amount of work all in one go it will be much more work for whoever is reviewing your pull request. Help them help you! :wink:
42
+
After writing new code or modifying existing code, please make sure to:
57
43
58
-
Are you new to Git and GitHub or just want a detailed guide on getting started with version control? Check out the [Version Control chapter](https://the-turing-way.netlify.com/version_control/version_control.html) in _The Turing Way_ Book!
* write tests in the `tests/` directory using [pytest](https://docs.pytest.org/en/7.4.x/).
46
+
* format the code using [black](https://github.com/psf/black)
59
47
60
-
### 3. Commit and Push
48
+
It would be great if you could also [update the documentation](contributing-docs.md) to reflect the changes you've made. If you plan to add a new emulator have a look at the [contributing emulators docs](contributing-emulators.md).
61
49
62
-
While making your changes, commit often and write good, detailed commit messages. [This blog](https://chris.beams.io/posts/git-commit/) explains how to write a good Git commit message and why it matters. It is also perfectly fine to have a lot of commits - including ones that break code. A good rule of thumb is to push up to GitHub when you _do_ have passing tests then the continuous integration (CI) has a good chance of passing everything. 😸
50
+
### 3. Commit and Push
63
51
64
-
Please do not re-write history! That is, please do not use the [rebase](https://help.github.com/en/articles/about-git-rebase) command to edit previous commit messages, combine multiple commits into one, or delete or revert commits that are no longer necessary.
52
+
While making your changes, commit often and write good, detailed commit messages. [This blog](https://chris.beams.io/posts/git-commit/) explains how to write a good Git commit message and why it matters.
65
53
66
54
### 4. Open a Pull Request
67
55
68
-
We encourage you to open a pull request as early in your contributing process as possible. This allows everyone to see what is currently being worked on. It also provides you, the contributor, feedback in real-time from both the community and the continuous integration as you make commits (which will help prevent stuff from breaking).
69
-
70
-
GitHub has a [nice introduction](https://guides.github.com/introduction/flow) to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions :balloon:.
56
+
We encourage you to open a pull request as early in your contributing process as possible. This allows everyone to see what is currently being worked on. It also provides you, the contributor, feedback in real-time. GitHub has a [nice introduction](https://guides.github.com/introduction/flow) to the pull request workflow.
71
57
72
58
## First-timers' Corner
73
59
74
-
If you're new to the project, we recommend starting with issues labeled as ["good first issue"](https://github.com/alan-turing-institute/autoemulate/issues?q=is:issue+is:open+label:%22good+first+issue%22). These are typically simpler tasks that offer a great starting point.
75
-
76
-
There's also the label ["thoughts welcome"](https://github.com/alan-turing-institute/autoemulate/issues?q=is:issue+is:open+label:%22thoughts+welcome%22), which allows for you to contribute with discussion points in the issues, even if you don't want to
77
-
or cannot contribute to the codebase.
78
-
79
-
If you feel ready for it, you can also open a new issue. Before you open a new issue, please check if any of [our open issues](https://github.com/alan-turing-institute/autoemulate/issues) cover your idea already. If you open a new issue, please follow our basic guidelines laid out in our issue templates, which you should be able to see if you [open a new issue](https://github.com/alan-turing-institute/autoemulate/issues/new/choose).
60
+
Just to-reiterate: We welcome all contributions, no matter how big or small! If anything in this guide is unclear, please reach out to ask or simply ask questions in a PR or issue.
80
61
81
62
## Reporting Bugs
82
63
83
64
Found a bug? Please open an issue here on GitHub to report it. We have a template for opening issues, so make sure you follow the correct format and ensure you include:
84
65
85
-
- A clear title.
86
-
- A detailed description of the bug.
87
-
- Steps to reproduce it.
88
-
- Expected versus actual behavior.
66
+
* A clear title.
67
+
* A detailed description of the bug.
68
+
* Steps to reproduce it.
69
+
* Expected versus actual behavior.
89
70
90
71
## Recognising Contributions
91
72
92
-
We value and recognise every contribution. All contributors will be acknowledged in the [contributors](https://github.com/alan-turing-institute/autoemulate/tree/main#contributors) section of the README. Notable contributions will also be highlighted in our sprint demo meetings.
73
+
All contributors will be acknowledged in the [contributors](https://github.com/alan-turing-institute/autoemulate/tree/main#contributors) section of the README.
93
74
94
-
AutoEmulate follows the [all-contributors](https://github.com/kentcdodds/all-contributors#emoji-key) specifications. The all-contributors bot usage is described [here](https://allcontributors.org/docs/en/bot/usage). You can see a list of current contributors here.
75
+
AutoEmulate follows the [all-contributors](https://github.com/kentcdodds/all-contributors#emoji-key) specifications. The all-contributors bot usage is described [here](https://allcontributors.org/docs/en/bot/usage).
95
76
96
77
To add yourself or someone else as a contributor, comment on the relevant Issue or Pull Request with the following:
97
78
@@ -108,8 +89,8 @@ What happens if you accidentally run the bot before the previous run was merged
108
89
If you're stuck or need assistance:
109
90
110
91
<!-- #TODO #148 - Check our [FAQ](<ADD LINK TO FAQ DOCUMENT>) section first. -->
111
-
- Reach out <!-- on Slack or --> via email for personalised assistance. (See ["Get in touch"](#get-in-touch) above for links.)
112
-
- Consider pairing up with a another contributor for guidance. <!-- You can always find us in the Slack channel and we're happy to chat! -->Contact us for guidance on this topic
92
+
* Reach out <!-- on Slack or --> via email for personalised assistance. (See [Get in touch](#get-in-touch) above for links.)
93
+
* Consider pairing up with a another contributor for guidance. <!-- You can always find us in the Slack channel and we're happy to chat! -->Contact us for guidance on this topic
113
94
114
95
**Once again, thank you for considering contributing to AutoEmulate! We hope you enjoy your contributing experience.**
115
96
@@ -122,3 +103,13 @@ Every contributor is expected to adhere to our Code of Conduct. It outlines our
122
103
----
123
104
124
105
These Contributing Guidelines have been adapted from the [Contributing Guidelines](https://github.com/the-turing-way/the-turing-way/blob/main/CONTRIBUTING.md#recognising-contributions) of [The Turing Way](https://github.com/the-turing-way/the-turing-way)! (License: CC-BY)
106
+
107
+
## Get in touch
108
+
109
+
**Email**: For any inquiries, please reach out to lead Developer Martin Stoffel, <[email protected]>.
110
+
111
+
<!-- The easiest way to get involved with the active development of AutoEmulate is to join our regular community calls. The community calls are currently on a hiatus but if you are interested in participating in the forthcoming community calls, which will start in 2024, you should join our Slack workspace, where conversation about when to hold the community calls in the future will take place. -->
112
+
113
+
<!--
114
+
**Slack Workspace**: Join our [AutoEmulate Slack channel](<LINK TO SIGN-UP OR TO THE SLACK TEAM>) for discussions, queries, and community interactions. Send us an email at [email protected] to request an invite.
Simulations of physical systems are often slow and need lots of compute, which makes them unpractical for real-world applications like digital twins, or when they have to run thousands of times for sensitivity analyses. The goal of `AutoEmulate` is to make it easy to replace simulations with fast, accurate emulators. To do this, `AutoEmulate` automatically fits and compares various models, ranging from simple models like Radial Basis Functions and Second Order Polynomials to more complex models like Support Vector Machines, Gaussian Processes and Conditional Neural Processes to find the best emulator for a simulation.
10
+
Simulations of physical systems are often slow and need lots of compute, which makes them unpractical for real-world applications like digital twins, or when they have to run thousands of times for sensitivity analyses. The goal of `AutoEmulate` is to make it easy to replace simulations with fast, accurate emulators. To do this, `AutoEmulate` automatically fits and compares various emulators, ranging from simple models like Radial Basis Functions and Second Order Polynomials to more complex models like Support Vector Machines, Gaussian Processes and Conditional Neural Processes to find the best emulator for a simulation.
There's currently a lot of development, so we recommend installing the most current version from GitHub:
20
17
@@ -35,7 +32,7 @@ cd autoemulate
35
32
poetry install
36
33
```
37
34
38
-
## quick start
35
+
## Quick start
39
36
40
37
```python
41
38
import numpy as np
@@ -70,7 +67,7 @@ si = ae.sensitivity_analysis(emulator)
70
67
ae.plot_sensitivity_analysis(si)
71
68
```
72
69
73
-
## documentation
70
+
## Documentation
74
71
75
72
You can find tutorials, FAQs and the API reference [here](https://alan-turing-institute.github.io/autoemulate/). The documentation is still work in progress.
0 commit comments