From 38ac5fdac0a4b62f39251ca2875e5c393726689a Mon Sep 17 00:00:00 2001 From: Spencer Bliven Date: Tue, 22 Oct 2024 12:01:46 +0200 Subject: [PATCH 1/2] Update contributing.md - Remove templates. These are now filled from .github/ISSUE_TEMPLATE - Update text - Make v4.x/contributing.md visible v3.x and v4.x are mostly the same, except for dropping the link to Development_Methods.md, which is outdated now. --- Development/v3.x/Contributing.md | 86 ++++++++-------------------- Development/v4.x/contributing.md | 34 +++++++++++ Development/v4.x/old/Contributing.md | 69 ---------------------- SUMMARY.md | 1 + 4 files changed, 60 insertions(+), 130 deletions(-) create mode 100644 Development/v4.x/contributing.md delete mode 100644 Development/v4.x/old/Contributing.md diff --git a/Development/v3.x/Contributing.md b/Development/v3.x/Contributing.md index e979f634..83bfa8a8 100644 --- a/Development/v3.x/Contributing.md +++ b/Development/v3.x/Contributing.md @@ -1,69 +1,33 @@ # Contributing -There are 3 core ways to get involved with the Data Catalogue project: - -1. Documentation - Fixing errors, covering weaker areas, adding examples -2. Github Issues - This should be the first area to focus on for those that want to amend the code. To see how the project is developed, see the [Git Workflow page.](./Development_Methods.md) -3. Testing - -For information about the development method we follow, please check [Development Methodology.](./Development_Methods.md) +There are many to get involved with the SciCat project: + +1. Documentation - Fixing errors, covering weaker areas, adding examples. Documentation + is divided between the + [homepage](https://github.com/SciCatProject/scicatproject.github.io), + [documentation pages](https://github.com/SciCatProject/documentation), and READMEs in + the repositories. +2. Github Issues - This should be the first area to focus on for those that want to + amend the code. To see how the project is developed, see the [Git Workflow + page.](./Development_Methods.md) +3. [Testing](./Testing.md) - Most repositories contain unit tests. Integration between + components is tested with [scicatlive](https://github.com/SciCatProject/scicatlive), + which is also the easiest way to run and develop SciCat locally. +4. Development - For information about the development method we follow, please check + [Git Flow Workflow](./Development_Methods.md). + +Communication is done through github issues, a slack channel, and a biweekly developer +meeting. Please [contact](https://scicatproject.github.io/#team) the project leader, Max +Novelli, for more information on getting involved. ## Issues -Issues are handled within the Github Issue tracker and should follow the template: - -```markdown -## Issue Name - -### Summary - -### Steps to Reproduce - -### Current Behaviour - -### Expected Behaviour - -### Extra Details - -Here you should include details about the system (if it is unique) and possible information about a fix (feel free to link to code where relevant). Screenshots/GIFs are also fine here. - -``` - - +Issues are handled within the Github Issue tracker. Please follow the provided template +for each repository. ## Merge Requests -There should be **no** pushing directly to the `master` or `develop` branches. To implement a fix, one should open a branch with the naming: `hotfix/ISSUE-NAME` from the `develop` branch and complete all work there. When it is complete, a Merge Request should be opened that follows this template: - -```markdown -## Description - -## Motivation - -Link to any open issues here - -## Fixes: - -* -* - -## Changes: - -* -* - -## Tests included/Docs Updated? - -- [ ] Included for each change/fix? -- [ ] Passing? (Merge will not be approved unless this is checked) -- [ ] Docs updated? - -## Extra Information/Screenshots -``` - -When the request is created, it should be assigned to any other appropriate team member with `develop` as the target branch. Tests **must** be written for all features/changes made and any major changes should be updated in the `docs` repo. - - - - - +There should be **no** pushing directly to the `main`, `master` or `develop` branches. +To implement a fix, fork the repository and create a branch (eg `fix/ISSUE-NAME`) +complete all work there. When it is complete, open a Pull Request, which will be +reviewed and merged by the core developers. diff --git a/Development/v4.x/contributing.md b/Development/v4.x/contributing.md new file mode 100644 index 00000000..2b2c6220 --- /dev/null +++ b/Development/v4.x/contributing.md @@ -0,0 +1,34 @@ +# Contributing + +There are many to get involved with the SciCat project: + +1. Documentation - Fixing errors, covering weaker areas, adding examples. Documentation + is divided between the + [homepage](https://github.com/SciCatProject/scicatproject.github.io), + [documentation pages](https://github.com/SciCatProject/documentation), and READMEs in + the repositories. +2. Github Issues - This should be the first area to focus on for those that want to + amend the code. To see how the project is developed, see the [Git Workflow + page.](./Development_Methods.md) +3. [Testing](./testing.md) - Most repositories contain unit tests. Integration between + components is tested with [scicatlive](https://github.com/SciCatProject/scicatlive), + which is also the easiest way to run and develop SciCat locally. +4. Development - Check individual repositories for more information on how to contribute + code ([frontend](https://github.com/SciCatProject/frontend), + [backend](https://github.com/SciCatProject/scicat-backend-next)). + +Communication is done through github issues, a slack channel, and a biweekly developer +meeting. Please [contact](https://scicatproject.github.io/#team) the project leader, Max +Novelli, for more information on getting involved. + +## Issues + +Issues are handled within the Github Issue tracker. Please follow the provided template +for each repository. + +## Merge Requests + +There should be **no** pushing directly to the `main`, `master` or `develop` branches. +To implement a fix, fork the repository and create a branch (eg `fix/ISSUE-NAME`) +complete all work there. When it is complete, open a Pull Request, which will be +reviewed and merged by the core developers. diff --git a/Development/v4.x/old/Contributing.md b/Development/v4.x/old/Contributing.md deleted file mode 100644 index e979f634..00000000 --- a/Development/v4.x/old/Contributing.md +++ /dev/null @@ -1,69 +0,0 @@ -# Contributing - -There are 3 core ways to get involved with the Data Catalogue project: - -1. Documentation - Fixing errors, covering weaker areas, adding examples -2. Github Issues - This should be the first area to focus on for those that want to amend the code. To see how the project is developed, see the [Git Workflow page.](./Development_Methods.md) -3. Testing - -For information about the development method we follow, please check [Development Methodology.](./Development_Methods.md) - -## Issues - -Issues are handled within the Github Issue tracker and should follow the template: - -```markdown -## Issue Name - -### Summary - -### Steps to Reproduce - -### Current Behaviour - -### Expected Behaviour - -### Extra Details - -Here you should include details about the system (if it is unique) and possible information about a fix (feel free to link to code where relevant). Screenshots/GIFs are also fine here. - -``` - - - -## Merge Requests - -There should be **no** pushing directly to the `master` or `develop` branches. To implement a fix, one should open a branch with the naming: `hotfix/ISSUE-NAME` from the `develop` branch and complete all work there. When it is complete, a Merge Request should be opened that follows this template: - -```markdown -## Description - -## Motivation - -Link to any open issues here - -## Fixes: - -* -* - -## Changes: - -* -* - -## Tests included/Docs Updated? - -- [ ] Included for each change/fix? -- [ ] Passing? (Merge will not be approved unless this is checked) -- [ ] Docs updated? - -## Extra Information/Screenshots -``` - -When the request is created, it should be assigned to any other appropriate team member with `develop` as the target branch. Tests **must** be written for all features/changes made and any major changes should be updated in the `docs` repo. - - - - - diff --git a/SUMMARY.md b/SUMMARY.md index 44f2f741..47063c4a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -39,6 +39,7 @@ - [Git Flow Workflow](Development/v3.x/Development_Methods.md) - [v4.x](Development/v4.x/README.md) - [Overview](Development/v4.x/overview.md) + - [Contributing](Development/v4.x/contributing.md) - [An Introduction to the Data Model](Development/v4.x/Data_Model.md) - [Running the Components](Development/v4.x/running.md) - [Configuration](Development/v4.x/configuration.md) From 5bca1f4257f7fc0a23ce34d6251d6b092b8f900a Mon Sep 17 00:00:00 2001 From: Spencer Bliven Date: Tue, 22 Oct 2024 17:35:31 +0200 Subject: [PATCH 2/2] Fix links to contributing and developers_guide --- Development/v3.x/README.md | 6 +++--- Development/v4.x/README.md | 2 +- Development/v4.x/contributing.md | 6 ++---- Development/v4.x/developers_guide.md | 10 +++++----- SUMMARY.md | 1 + 5 files changed, 12 insertions(+), 13 deletions(-) diff --git a/Development/v3.x/README.md b/Development/v3.x/README.md index 3f6ae5ad..d0c234db 100644 --- a/Development/v3.x/README.md +++ b/Development/v3.x/README.md @@ -2,7 +2,7 @@ This guide aims to help developers understand the overall structure of the software and therefore enables people to contribute to the development of the software. See also the [Overview in the Operator Manual](../Operator/) for a helicopter view of the involved components. -If you want to contribute to the software you should also read the [Contributing](../Development/Development_Methods.html) section, which among others links to the git workflow to be used. +If you want to contribute to the software you should also read the [Contributing](./Contributing.md) section, which among others links to the git workflow to be used. # Getting an development environment set up @@ -21,8 +21,8 @@ The most important part to understand is how loopback works, because it is the p ## Web Browser Client (Frontend) -* [Angular 9+](https://angular.io/) -* [Angular Material Widgets and Design](https://material.angular.io/) +* [Angular 9+](https://angular.io/) +* [Angular Material Widgets and Design](https://material.angular.io/) * [NGRX for State Management](https://ngrx.io/) * [Loopback SDK generator for Angular](https://github.com/mean-expert-official/loopback-sdk-builder) diff --git a/Development/v4.x/README.md b/Development/v4.x/README.md index 0a8828b8..6407d84c 100644 --- a/Development/v4.x/README.md +++ b/Development/v4.x/README.md @@ -2,7 +2,7 @@ This guide aims to help developers understand the overall structure of the software and therefore enables people to contribute to the development of the software. See also the [Overview in the Operator Manual](../Operator/) for a helicopter view of the involved components. -If you want to contribute to the software you should also read the [Contributing](../Development/Development_Methods.html) section, which among others links to the git workflow to be used. +If you want to contribute to the software you should also read the [Contributing](./contributing.md) section. # Getting an development environment set up diff --git a/Development/v4.x/contributing.md b/Development/v4.x/contributing.md index 2b2c6220..7e1c4ad8 100644 --- a/Development/v4.x/contributing.md +++ b/Development/v4.x/contributing.md @@ -8,14 +8,12 @@ There are many to get involved with the SciCat project: [documentation pages](https://github.com/SciCatProject/documentation), and READMEs in the repositories. 2. Github Issues - This should be the first area to focus on for those that want to - amend the code. To see how the project is developed, see the [Git Workflow - page.](./Development_Methods.md) + amend the code. 3. [Testing](./testing.md) - Most repositories contain unit tests. Integration between components is tested with [scicatlive](https://github.com/SciCatProject/scicatlive), which is also the easiest way to run and develop SciCat locally. 4. Development - Check individual repositories for more information on how to contribute - code ([frontend](https://github.com/SciCatProject/frontend), - [backend](https://github.com/SciCatProject/scicat-backend-next)). + code. For an overview, see the [developer guide](./developers_guide.md). Communication is done through github issues, a slack channel, and a biweekly developer meeting. Please [contact](https://scicatproject.github.io/#team) the project leader, Max diff --git a/Development/v4.x/developers_guide.md b/Development/v4.x/developers_guide.md index cc024813..8b078196 100644 --- a/Development/v4.x/developers_guide.md +++ b/Development/v4.x/developers_guide.md @@ -1,12 +1,12 @@ # SciCat Data Catalogue Developer Guide -This guide aims to help developers understand the overall structure of the software and therefore enables people to contribute back to develop and improve this tool. +This guide aims to help developers understand the overall structure of the software and therefore enables people to contribute back to develop and improve this tool. Please refer to [Overview in the Operator Manual](../Operator/) for a bird-eye view of the components that are part of SciCat. -If you want to contribute to this software, please read the [Contributing](../Development/Development_Methods.html) section, which among others links to the git workflow to be used. +If you want to contribute to this software, please read the [Contributing](./contributing.md) section, which among others links to the git workflow to be used. ## Introduction to SciCat architecture -SciCat architecture has been designed embracing the micro-services philosophy. +SciCat architecture has been designed embracing the micro-services philosophy. The software has two main components: * Frontend * Backend @@ -27,8 +27,8 @@ Technologies: ### Frontend The frontend provides a single page UI application running in the browser intended to provide a easy to use interface to the backend functionalities Technologies: -* [Angular 9+](https://angular.io/) -* [Angular Material Widgets and Design](https://material.angular.io/) +* [Angular 9+](https://angular.io/) +* [Angular Material Widgets and Design](https://material.angular.io/) * [NGRX for State Management](https://ngrx.io/) * [Loopback SDK generator for Angular](https://github.com/mean-expert-official/loopback-sdk-builder) diff --git a/SUMMARY.md b/SUMMARY.md index 47063c4a..2d09f6ee 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -40,6 +40,7 @@ - [v4.x](Development/v4.x/README.md) - [Overview](Development/v4.x/overview.md) - [Contributing](Development/v4.x/contributing.md) + - [Developer Guide](Development/v4.x/developers_guide.md) - [An Introduction to the Data Model](Development/v4.x/Data_Model.md) - [Running the Components](Development/v4.x/running.md) - [Configuration](Development/v4.x/configuration.md)